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1. Introduction to the Zmacs Manual 
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Overview of the Zmacs Manual 



Scope 



Organization 



The Zmacs Manual is primarily a reference manual and is intended 
for all users of Zmacs on the Lisp Machine. It contains both 
conceptual overview and reference material that together describe 
the Zmacs editor. We assume that you have already read the 
User's Guide to Symbolics Computers. 



The first three chapters contain introductory material for users who 
are unfamiliar with Zmacs concepts. Experienced users can skim 
the remaining chapters, which are organized according to editing 
function, and use them as reference material. 

"Introduction" gives an overview of Zmacs and describes Zmacs 
documentation conventions in this manual. 

"Getting Started" introduces basic Zmacs concepts and commands, 
such as how to enter text, move the cursor, and make simple 
corrections. 

"Getting Help" describes ways to get out of trouble and how to get 
Zmacs information during editing. 

"Moving the Cursor" includes descriptions of both mouse and 
keyboard motion commands. 

"Deleting and Transposing Text" explains Zmacs deletion and text 
retrieval concepts, as well as the ways to delete and transpose text. 

"Working With Regions" tells how to manipulate blocks of text. 

"Searching, Replacing, and Sorting" describes the commands for 
locating and replacing character strings in one or many files. 

"Manipulating Buffers and Files" gives more information on 
manipulating blocks of text, inserting files, keeping track of 
everything, and editing your directory. 

"Setting the Major Mode" documents the major editing modes and 
their characteristics. 

"Changing Case and Indentation" includes many commands for 
changing code, comments, or text to uppercase or lowercase, as well 
as commands for handling white space, indentation, and formatting. 

"Editing Lisp Programs" the ways in which Zmacs is tailored for 
use in writing and editing programs in Lisp. 

"Customizing the Zmacs Environment" describes how to fine tune 
your Zmacs environment using modes to set it up, keyboard macros 
to perform special editing tasks, binding keys to the commands of 
your choice, setting Zmacs variables to alter your standard system 
aults, and saving the customized environment in init files. 
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Appendix A summarizes Zmacs help commands according to the 
context in which they are available. 
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Overview 



Commands 



Zmacs, the Lisp Machine editor, is built on a large and powerful 
system of text-manipulation functions and data structures, called 
Zwei. 

Zwei is not an editor itself, but rather a system on which other 
text editors are implemented. For example, in addition to Zmacs, 
the Zmail mail reading system also uses Zwei functions to allow 
editing of a mail message as it is being composed or after it has 
been received. The subsystems that are established upon Zwei are: 

• Zmacs, the editor that manipulates text in files 

• Dired, the editor that manipulates directories represented as text 
in files 

• Zmail, the editor that manipulates text in mailboxes 

• Converse, the editor that manipulates text in messages 

Since these subsystems share Zwei in the dynamically linked Lisp 
environment, many of the commands available as Zmacs commands 
are available in other editing contexts as well. 

In this manual, we discuss Zmacs commands in the context of 
Zmacs only. We also describe Dired, the directory editor, since it is 
used within Zmacs. 



Zmacs commands are Lisp functions that perform the editing work. 
Every Zmacs command has a name, and many commands are 
bound to keys. When a command is bound to a keystroke 
combination, you invoke it by pressing those keys. For example, 
the Forward Word command is invoked by typing the keystroke 
n-F. When a command is not bound to a set of keystrokes, Zmacs 
calls it an extended command and you invoke it using its name 
preceded by n-X. For example, the command View Mail, an 
extended command, is invoked by View Mail n-x. 

Command tables assign keystrokes and names to commands. Each 
time you press a key, Zmacs looks up the function associated with 
that key. For ordinary characters, the function corn-standard, in 
the standard command table, inserts the character once. 



Keystrokes 



A keystroke has a character component and a modifier component, 
and is performed by pressing a primary key (alphanumeric), possibly 
while holding down a shift key or a group of shift keys. The 
primary key held down with either the SHIFT or SYMBOL keys 
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determines the character part of a keystroke. Whether you hold 
down the other shift keys, CONTROL, METfi, HYPER, and SUPER, 
determines the modifier part of the keystroke. 

In general, commands that begin with a CONTROL (c-) key modifier 
operate on single characters, commands that begin with a met A (n-) 
key modifier operate on words, sentences, paragraphs, and regions, 
and commands that begin with a control METfl (c-n-) modifier 
operate on Lisp code. 

Prefix character commands consist of more than one keystroke per 
command. For example, to invoke the command c-X F, you first 
type the prefix character c-X and then the primary key F. Prefix 
character commands are not case-sensitive — that is, Zmacs 
converts a lowercase character following a prefix character command 
(like c-X) to uppercase. For example, c-X f is equivalent to c-X F. 

Zmacs commands are self-delimiting. Unless otherwise specified, 
you do not need to type a carriage return or other terminating 
character to finish typing a command. 

Extended Commands 

Extended commands extend the range of commands past the one- 
or-two-keystroke limitation. You invoke Zmacs extended commands 
by name using the n-x command: 

n-X Extended Command 

Prompts for the name of a Zmacs command and executes that 
command. 

Command completion is provided. 

See the section "Completion in the Minibuffer". 

Command Tables 

There is always a currently active command table (comtab). When 
you invoke a command, Zmacs looks it up in the associated 
command table, checks to see if it is valid in the current context, 
and performs the function. Zmacs uses many comtabs, including 
the standard comtab, a comtab for commands that begin with the 
c-X prefix, and a comtab for reading pathnames in the minibuffer. 

Many commands have no meaning outside their own limited 
context. Sometimes you might get a message or see online 
documentation about a command that says 

Not available in current context. Those commands that are not 
accessible via a keystroke and not accessible via n-x are likoly to be 
commands that do not work in the current context. For example, 
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a command that is part of Dired is only available on a key when 
you are in Dired. 

You can invoke a command that is not available in the current 
comtab with the c-n-X command. c-n-X works like n-X: you press 
the keys and then type the command name in the minibuffer. 
This is primarily intended for debugging new editor commands that 
have not yet been installed on any key. Using c-n-X to invoke a 
command that is not in the current comtab because it works only 
in some other context is a sure way to get into trouble. 

c-n-X Any Extended Command 

Prompts for the name of a Zmacs command and executes that 
command. 

Command completion is provided. 
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Zmacs Notation 
Conventions and Examples 

The word current, when describing a word, line, paragraph, page, or 
any Zmacs-recognizable piece of text, refers to the text that 
currently contains (or immediately follows) the cursor. 

The invocation of a command shows exactly what keys you must 
press to invoke, or call, a command. We use the following format 
to describe Zmacs commands: 

i nvocat i on Name 

a 1 te mate i nvocat i on 
alternate invocation 

Formal description of command 

Since each extended (n-X) command contains its name as part of its 
invocation, we do not repeat the name again on that line. 

Example 1 of Zmacs 
Notation Conventions 

m-> Goto End 

Moves point to the end of the buffer. 

With a numeric argument n between and 10, moves point to a 
place n/10 of the way from the end of the buffer to the beginning. 

(The n-> command goes to the end of the buffer — its name is 
Goto End.) 

Example 2 of Zmacs 
Notation Conventions 

Dired (n-x) 

Prompts for the name of a directory to edit with Dired. 

(The Dired (n-x) command is an extended command that enters 
the directory editor.) 

Example 3 of Zmacs 
Notation Conventions 

m-M Back To Indentation 

c-m-M 

n-RETURN 

c-n-RETURN 

Positions point before the first nonblank character on the current 
line. 

(Back to Indentation has several possible invocations that all move 
back to the first nonblank character on the line.) 
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Entering Zmacs 



Introduction to 
Entering Zmacs 

You can enter, or invoke, the editor in several ways: Press 
select E, use the mouse, or run either the function ed or the 
function zwehedit-functions. You can also use the command 
Select Activity, specifying either Zmacs or Editor as its argument. 



Entering Zmacs 
With SELECT E 



You can invoke the editor by pressing the SELECT key and then the 
letter E: 

• If you have already been in the editor since booting the machine, 
Zmacs returns you to the same place in the same buffer that you 
last used. 

• If this is the first time you are entering Zmacs since booting the 
machine, Zmacs puts you in an empty buffer named *Buffer-l*. 

SELECT E enters or returns you to the editor from anyplace in the 
system, not just when you are talking to Lisp. 



Entering Zmacs 
with the Mouse 



Entering Zmacs 
with ed 



You can invoke the editor using the mouse. 

Summon a System menu by clicking right twice [(R2)]. Then click 
left on the Edit option [Edit (L)], which puts you into a Zmacs 
buffer. As for SELECT E, if you are returning to the editor Zmacs 
puts you back at the same place in the same buffer, and if you are 
entering Zmacs for the first time it puts you in an empty buffer. 



The Lisp function ed enters Zmacs from a Lisp Listener. See the 
function ed in User's Guide to Symbolics Computers. 

When reentering Zmacs within a login session, ed enters the editor, 
preserving its state as it was when you left. When entering Zmacs 
for the first time during a login session, ed initializes Zmacs and 
creates an empty buffer. 

arg can have these values. 

Value Description 

t The ed function enters the editor, 

creates an empty buffer, and selects it. 

Pathname or string The ed function enters the editor and 
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Defined symbol 



The symbol zwei:reload 



finds or creates a buffer with the 
specified file in it. 

The editor tries to find the source 
definition of that symbol for you to 
edit. A defined symbol can be, for 
example, a function, macro, variable, 
flavor, or system. 

The system reinitializes the editor. 
This destroys all existing buffers, so 
use this only if you have to. 



Entering Zmacs 

with zwei:edit-fimctions 

The Lisp function zweiredit-functions also enters Zmacs from a 
Lisp Listener. 



zweiredit-functions 



Function 



zweiredit-functions is like ed in that inside the editor process it 
throws you back into the editor, whereas from another process it 
just sends a message to the editor and selects the editor's window. 
zweiredit-functions gives spec-list to the editor in the same way 
that Edit Callers and similar editor commands would. See the 
section "The Zmacs Edit Callers Commands", page 183. 

This command is useful when you have collected the names of 
things that you need to change, for example, using some program 
to generate the list, spec-list is a list of definitions; these are either 
function specs (if the definitions are functions) or symbols. 

Zmacs sorts the list into an appropriate order, putting definitions 
from the same file together, and creates a support buffer called 
*Function-Specs-to-Edit-7i*. It selects the editor buffer containing 
the first definition in the list. 
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Introduction to 
Zmacs Help 



Zmacs has many features that provide information about Zmacs 
commands, existing code, buffers, and files. Two features are 
generally useful: the HELP key and completion. See the section 
"Getting Help in Zmacs", page 41. 



Introduction to HELP 

Pressing the help key in a Zmacs editing window gives information 
about Zmacs commands and variables. For descriptions of Zmacs 
variables: See the section "How to Specify Zmacs Variable 
Settings", page 210. The kind of information it displays depends on 
the key you press after help. 



help ? 
help fl 



HELP C 

HELP D 

HELP L 
HELP U 

HELP V 



HELP U 



HELP SPACE 



Displays a summary of HELP options. 

Displays names, key bindings, and brief 
descriptions of commands whose names contain a 
string you specify. (The A refers to apropos, the 
name of the function that finds the commands 
and displays their documentation.) 

Displays the name and description of a command 
bound to a key you specify. 

Displays documentation for a command whose 
name you specify. 

Displays a listing of the last 60 keys you pressed. 

Offers to undo the last major Zmacs operation, 
such as sorting or filling, when possible. 

Displays the names and values of Zmacs variables 
whose names contain a string you specify. For 
descriptions of Zmacs variables: See the section 
"How to Specify Zmacs Variable Settings", page 
210. 

Displays the key binding for a command you 
specify. (The W refers to where.) 

Repeats the last HELP command. 



Introduction to Completion 

Some Zmacs operations require you to provide names — for 
example, names of extended commands, Lisp objects, buffers, or 
files. Often you do not have to type all the characters of a name; 
Zmacs offers completion over some names. When completion is 
available, the word Completion appears in parentheses above the 
right side of the minibuffer. 
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You can request completion when you have typed enough 
characters to specify a unique word or name. For extended 
commands and most other names, completion works on initial 
substrings of each word. For example, n-x c SPfiCE b is sufficient 
to specify the extended command Compile Buffer. SPRCE, complete, 
RETURN, and END complete names in different ways. Press HELP or 
click right once, [(R)], on the editor window or minibuffer to list 
possible completions for the characters you have typed, c-/ displays 
every command that contains the substring. 

SPACE Completes words up to the current word. 

HELP or c-? Displays possible completions in the typeout area. 

[(R)] Pops up a menu of possible completions. 

c-/ Runs Apropos for each of the partially typed 

words in the name. 

COMPLETE Completes as much as possible. This could be 

the full name. 

RETURN or END Confirms the name if possible, whether or not 
you have seen the full name. 



Introduction to Yanking 

Yanking helps you to get back any text that you have typed or 
deleted, by retrieving it from a history. A history remembers 
commands and pieces of text, placing them in a history list in stack 
order, with the newer elements at the top of the history and the 
older elements toward the bottom. 

Yanking commands yank back an element of a history from any 
position in the history list that you specify: 

Yanking in the kill history: 

c-0 c-Y Displays the elements of the kill history (saved 

text). Click left on (N more elements in 
history.) to display those not shown. 

c-Y Yanks the first element in the kill history. 

n-Y After c-Y, yanks the previous element in the kill 

history. Subsequent n-Ys move down the kill 
history list. 

Yanking in the command history: 

c-0 c-n-Y Displays the elements of the command history 

(editor commands that use the minibuffer in any 
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way). Click left on (N more elements in 
history.) to display those not shown. 

c-n-Y Yanks the first element in the command history. 

n-Y After c-n-Y, yanks the previous element in the 

command history. Subsequent n-Ys move down 
the command history list. 

For complete descriptions of killing and yanking: See the section 
"Deleting and Transposing Text in Zmacs", page 71. 
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Introduction to 
the Organization 
of the Screen 

Zmacs divides its window into several areas: the editor window, the 
echo area, and the mode line, each of which contains its own type 
of information. 

Zmacs Editor Window 

The biggest area, the editor window, shows the text you are 
editing. You can edit several different items at once with Zmacs; 
each item is edited in a separate editing environment called a 
buffer. 

Editor Window's Buffer 

Zmacs gives every buffer a name. At any time you are editing only 
one of them, the selected buffer. When we speak of what some 
command does to "the buffer", we are talking about the currently 
selected buffer. Multiple buffers in Zmacs make it easy to switch 
among several files; the mode line tells you which one you are 
editing. 

Editor Window's 

Cursor and Point 

The small blinking rectangle, the cursor, usually appears somewhere 
within the buffer, showing the position of point, the location at 
which editing takes place. Although the cursor covers a single 
character, we consider point to be at the left edge of the cursor, 
between the character the cursor is blinking on and the previous 
character. 

Editor Window's Typeout 

When you request some other information from Zmacs (for 
example, if you ask for help or a listing of a file directory), Zmacs 
needs room to display this type of information. It prints this 
typeout in a typeout window (at the top of the editor window), 
which temporarily overlays the text in the editor window, using as 
much room as it needs. 

Since the typeout is not part of the file you are editing, Zmacs 
delineates it from the editor buffer by drawing a line across the 
window between them (if both are present). The typeout window 
goes away if you type any command; if you want to make it go 
away immediately but not do anything else, you can press SPRCE. 
The cursor, which appears at the end of the typeout, then moves 
back to its original location in the buffer. 
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Zmacs Echo Area 

A few lines at the bottom of the screen make up what is called the 
echo area. Echoing means displaying the commands that you type. 
Zmacs commands are usually not echoed at all, but if you pause in 
the middle of a multicharacter command, then all the characters 
(including numeric arguments and prefixes) typed so far are echoed. 
This is intended to prompt you for the rest of the command. The 
rest of the command is echoed, too, as you type it. This behavior 
is designed to give confident users optimum response, while giving 
hesitant users maximum feedback. 

Echo Area's Minibuffer 

Many Zmacs commands prompt you for additional information. 
This prompting happens in a small window within the echo area 
called the minibuffer. 

When Zmacs prompts you, the cursor in the main editing window 
stops blinking and a blinking cursor appears in the minibuffer. 
Over the minibuffer, in the Zmacs mode line, some prompting text 
appears, indicating what information Zmacs is prompting you for. 

When you type a response to the prompt, that response is inserted 
in the minibuffer. You can edit text in the minibuffer using the 
same Zmacs commands used in the main Zmacs window. 

When you are done typing (and possibly editing) a response to the 
prompt, the RETURN key finishes your response. 

Zmacs Mode Line 

The line above the echo area is known as the mode line. It is the 
line that usually starts with ZMACS (Fundamental). Its purpose is to 
display information about the current buffer. 

The mode line consists of: 

• The name of the major mode 

• The name of the minor mode(s), if any 

• The name of the buffer 

• The version number of the file 

• The status of the buffer 

• A message telling whether the buffer contents extend above 
and/or below the screen 

The mode line has this format: 

ZMACS (major-mode minor-mode(s)) buffer (version) buffer-status 
[position-flag] 
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Mode Line's Major-mode 

major-mode is always the name of the major mode you are in. At 
any time, Zmacs is in one and only one of its possible major modes. 
The major modes available include: 

• Fundamental mode (which Zmacs starts out in) 

• Text mode 

• Lisp mode 

• MACSYMA mode 

For full details about all the major modes, how they differ, and how 
to select one: See the section "Setting the Zmacs Major Mode", 
page 155. 

Mode Line's Minor-mode 

minor-mode is a list of the minor modes that are turned on at the 
moment. For example: 

Fill Auto Fill Mode 

Electric Shift-lock Electric Shift Lock Mode 

Abbrev Word Abbrev Mode 

Overwrite Overwrite Mode 

For more information: See the section "Built-in Customization 
Using Zmacs Minor Modes", page 195. 

Mode Line's Buffer 

buffer is the name of the workspace that holds the text you are 
editing. A buffer can be named in one of two ways: 

• By Zmacs, with a name that corresponds to the existing file that 
it contains or with its standard name for an empty buffer 

• By you, with any name you like 

When a buffer contains a file, the buffer name is the pathname of 
that file, rearranged with the file name first and the host and 
directory at the end. For a description of pathname components: 
See the section "Pathnames" in Reference Guide to Streams, Files, 
and I/O. When a buffer does not contain a file, the buffer name is 
a string. 

Buffers that do not contain files are empty, newly created, or 
temporary buffers. When Zmacs creates and names a buffer, that 
name begins and ends with an asterisk. When you create and 
name a buffer, on the other hand, its name is of your choosing. 
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When you first start up and enter Zmacs, your buffer is either: 

• An empty buffer called *Buffer-1*, which is the only one that 
exists when Zmacs starts up 

• A buffer containing an existing file, which Zmacs appropriately 
calls by its name 

For information on multiple buffers: See the section "Manipulating 
Buffers and Files in Zmacs", page 113. 

Mode Line's Version 

(version) is the version number most recently visited or saved. The 
mode line does not display any version number if the file is on a file 
system that does not support version numbers, such as UNIX. 

Mode Line's Buffer-status 

If the mode line displays *, then changes have been made in the 
buffer that have not been saved in the file. If the buffer has not 
been changed since it was read in or saved, the mode line does not 
display a asterisk. 

Mode Line's Position-flag 

When the mode line displays the message [More above], then your 
screen shows the end of your buffer contents; when the mode line 
shows [More below], then your screen shows the beginning of your 
buffer contents. When it says [More above and below], then the 
buffer contents extend above and below the part that the screen 
displays. When the display shows the entire buffer contents, this 
message does not appear at all. 

Mode Line Example 

ZMACS (Text) text. text /dess/doc/books/ VAX: * [More above and 
below] 

In this sample mode line, we are in Zmacs Text Mode, editing a file 
named text.text, which resides in the directory /dess/doc/books on 
the host named VAX. The file has been changed since we last 
saved it (indicated by the *), and the file contents extend above and 
below the portion that Zmacs displays on the screen. 
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Introduction to 
Inserting Text 

To insert new text anywhere in the buffer, position the cursor at 
the place you want the new text to go and type the new text. 
Zmacs always inserts characters at the cursor. The text to the 
right of the cursor is pushed along ahead of the text being inserted. 

Inserting Characters 

When you type in new text, you are actually issuing Zmacs 
commands. Ordinary printing characters are called self-inserting 
because when you type one, it inserts itself into the text in your 
buffer. 

You can give numeric arguments to the keystrokes that insert 
printing characters into the buffer; Zmacs interprets these 
arguments as repeat counts. See the section "Numeric 
Arguments", page 24. 

Example: c-80 * inserts a line of 80 asterisks at the cursor. 

Starting a New Line 

Newline characters delimit lines of text. They have no visible 
printed form, but are present at each line break. You can break 
one line into two lines by inserting a newline (pressing RETURN) 
where desired. Similarly, you can merge two lines into one by 
deleting the intervening newline. 

Correcting Typos 

To correct text you have just inserted, use the RUBOUT key. RUBOUT 
deletes the character before the cursor (not the one over which the 
cursor is positioned; that is the character after the cursor). The 
cursor and the rest of that line move to the left. 

When given a numeric argument, rubout saves the succession of 
deleted characters. 

Example: c-28 RUBOUT kills the previous 20 characters and saves 
them together. 

See the section "Deleting Vs. Killing Text", page 72. 

When the cursor is positioned on the first character on a line and 
you press RUBOUT, the preceding newline character is deleted and 
Zmacs appends the text on that line to the end of the previous 
line. 
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Wrapping Lines 

When you add too many characters to one line without breaking it 
with a RETURN, the line grows to occupy two (or more) lines on the 
screen, with an exclamation point at the extreme right margin of 
all but the last of them. The ! means that the following screen 
line is not really a distinct line in the file, but just the continuation 
of a line too long to fit the screen. 

Inserting 

Formatting Characters 

You can insert most characters directly into the buffer by simply 
typing them, but other characters act as editing commands and do 
not insert themselves. If you need to insert a character that is 
normally a command (for example, TAB or RUBOUT), use the c-Q 
(Quoted Insert) command first to tell Zmacs to insert the following 
character into the buffer literally. c-Q prompts in the echo area for 
the character to be inserted and inserts it into the text. 
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Overview of 
Numeric Arguments 

Many Zmacs commands take numeric arguments, which you type 
before the main command keystroke. Specify a numeric argument 
by pressing any combination of any of the modifier keys (c-, m-, s-, 
or h-) with the number. This way, you can type sequences of 
commands more easily without frequently alternating keys. 

Numeric arguments to commands appear in the echo area when 
you do not type the command immediately. With no delay, the 
argument does not appear. 

In general, use negative arguments to tell a command to move or 
act backwards. You can specify a negative argument by pressing 
any modifier key with the minus sign followed by the number. 
Most commands treat a numeric argument consisting of just a 
minus sign the same as -1. 

Example of 
Numeric Arguments 

c-F is the command to move the cursor forward one character. 

c-3 c-5 c-F moves point forward 35 characters; 

c — c-3 c-5 c-F moves point backward 35 characters. 

Throughout this manual, instead of writing out c-4 c-5 c-F or 
m-4 n-5 n-B, we usually abbreviate to c-45F or n-45B. 

Defaults to 
Numeric Arguments 

Many commands have default numeric arguments. This means 
that in the absence of a numeric argument, the command behaves 
as if the default argument were given. Most commands have a 
default argument of 1. This includes all the commands that 
interpret numeric arguments as repeat counts. Some commands 
have a different default and still others have no default: their 
behavior in the absence of a numeric argument is different from 
their behavior with a numeric argument. 

c-U Quadruple Numeric Arg 

This special command prefixes other commands, usually 
representing a numeric argument of 4. You can repeat c-U; it 
multiplies the numeric argument by 4 each time. For example, 
c-U c-U c-F moves point forward 16 characters. Sometimes instead 
of representing a numeric argument of 4, c-u alters the action of a 
command slightly; for example, when used with the command Set 
Pop Mark, c-U takes different actions with the mark. (For a 
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description of the Set Pop Mark command: See the section 
"Working with Regions in Zmacs", page 85.) 
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Description of 
Moving the Cursor 

To do more than insert characters, you have to know how to move 
the cursor. 

For complete descriptions of the commands summarized here and 
other cursor-moving commands: See the section "Moving the 
Cursor in Zmacs", page 53. 

Summary of 
Moving the Cursor 

c-fl Beginning of Line 

Moves to the beginning of the line. 

c-E End of Line 

Moves to the end of the line. 

c-F Forward 

Moves forward one character. 

c-B Backward 

Moves backward one character. 

n-F Forward Word 

Moves forward one word. 

n-B Backward Word 

Moves backward one word. 

n-E Forward Sentence 

Moves to the end of the sentence in text mode. 

n-fl Backward Sentence 

Moves to the beginning of the sentence in text mode. 

c-N Down Real Line 

Moves down one line. 

c-P Up Real Line 

Moves up one line. 

n-] Forward Paragraph 

Moves to the start of the next paragraph. 

n-[ Backward Paragraph 

Moves to the start of the current (or last) paragraph. 

c-x ] Next Page 

Moves to the next page. 

c-X [ Previous Page 

Moves to the previous page. 
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c-y, SCROLL Next Screen 

Moves down to display the next screenful of text. 

m-y, n-SCROLL Previous Screen 

Moves up to display the previous screenful of text. 

n-< Goto Beginning 

Moves to the beginning of the buffer. 

n-> Goto End 

Moves to the end of the buffer. 
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Description of 
Erasing Text 



Most commands that erase text from the buffer save it so that you 
can get it back if you change your mind, or move or copy it to 
other parts of the buffer. These commands are known as kill 
commands. The rest of the commands that erase text do not save 
it; they are known as delete commands. The delete commands 
include c-D and RUBOUT, which delete only one character at a time, 
and those commands that delete only spaces or line separators. 
(However, when given a numeric argument, c-D and rubout do save 
that sequence of deleted characters on the kill ring.) Commands 
that can destroy significant amounts of information generally kill. 
The commands' names and individual descriptions use the words 
"kill" and "delete" to say which they do. 

If you issue a kill command by mistake, you can retrieve the text 
with c-Y, the Yank command. For details on killing and retrieving 
text: See the section "Working with Regions in Zmacs", page 85. 



Summary of 
Erasing Text 



c-D 

Deletes the character after point. 

RUBOUT 

Deletes the character before point. 

n-D 

Kills forward one word. 

n-RUBOUT 

Kills backward one word. 

n-K 

Kills forward one sentence. 

c-X RUBOUT 

Kills backward one sentence. 

c-K 

Kills to the end of the line or kills an end of line 

c-w 

Kills region (from point to mark). 



Delete Forward 

Rubout 

Kill Word 

Backward Kill Word 

Kill Sentence 

Backward Kill Sentence 

Kill Line 

Kill Region 

Kill Sexp 



c-m-K 

Kills forward over exactly one Lisp expression. 

c-m-rubout Backward Kill Sexp 

Kills backward over exactly one Lisp expression. 
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n-\ Delete Horizontal Space 

Deletes any spaces or tabs around point. 

c-X c-0 Delete Blank Lines 

Deletes any blank lines following the end of the current line. 

n-* Delete Indentation 

Deletes RETURN and any indentation at front of line. 
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Description 



You do all your text editing in Zmacs buffers, which are temporary 
workspaces that can hold text. To keep any text permanently you 
must put it in a file. Files store data for any length of time. 

To edit the contents of a file using Zmacs, you create a buffer and 
copy the file contents into it. To add text to the end of the buffer, 
move point to the end of the buffer and type the new text. 
Editing proceeds in the buffer, not in the file. The file remains 
unchanged until you explicitly write the modified buffer contents to 
the file. 

If you create multiple buffers, Zmacs keeps track of which files you 
are editing in which buffers. This association allows you to use 
completion to switch among buffers while you are editing them; you 
do not have to type the file name more than once. Zmacs always 
displays the name of the file you are currently editing. 

The information in this section allows you to find or create and 
save a file. For complete information on buffers and files: See the 
section "Manipulating Buffers and Files in Zmacs", page 113. 



Summary 



c-X c-F 

Reads the specified file into a buffer. 

c-X c-s 

Saves out the changes to the current file. 

c-X B 

Selects the specified buffer. 

c-X c-w 

Writes out the buffer to the specified file. 



Find File 

Save File 

Select Buffer 

Write File 



Creating a Buffer 

Zmacs creates your initial buffer when you first enter the editor. 
To create other buffers, use c-X B, Select Buffer, to create an 
empty buffer or c-X c-F, Find File, to create either an empty 
buffer or a buffer containing a file. 

c-X B prompts for the name of the buffer to which you want to go. 
Type the buffer name and RETURN. If the buffer exists, Zmacs 
switches to that buffer and displays it on the screen. If the buffer 
does not already exist, Zmacs offers to let you create it by 
terminating the buffer name with c-RETURN. When you create a 
new (empty) buffer, the display is blank. 

The other way to create another buffer is c-X c-F, Find File. 
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(c-x c-F) is described in detail in "Editing Existing Files".) c-x c-F 
prompts for the name of a file, terminated by RETURN. 

When you type c-x c-F for the first time in a Zmacs session, 
Zmacs offers you, as a default file name, an empty file (with the 
Lisp suffix native to your host computer) in your home directory on 
your host computer. For example: 



System 


Empty Buffer Name 


Lisp Machine 


foo.lisp 


UNIX 


foo.l 


VMS 


foo.lsp 



Base and Syntax Default Settings for Lisp 



When you read a file that has a Lisp file type into the buffer, if 
that file does not begin with an attribute line containing Base and 
Syntax attributes, Zmacs warns that the file "has neither a Base 
nor a Syntax attribute" and announces that it will use the defaults, 
Base 10 and Zetalisp. See the section "Buffer and File Attributes". 



Buffer Contents with c-x c-F 



Saving a File 



The first time you use c-x c-F, you can create an empty buffer 
using the Zmacs default file name, create an empty buffer using a 
name that you specify, or create a buffer containing an existing file: 

• To create an empty buffer with the initial default file name as 
the one Zmacs associates with your buffer, press RETURN. 

• To create a new empty buffer, respond with any name. Zmacs 
switches to an empty buffer, gives the buffer the new name, and 
displays (New File) in the echo area. 

• To create a new buffer containing some file, respond to the 
prompt with the name of that file. Zmacs switches to an empty 
buffer, reads that file in, and names the buffer appropriately. 



Once you have the file in your buffer, you can make changes and 
then save the file with c-X c-S, the Save File command. This 
makes the changes permanent and actually changes the file. Until 
then, the changes are only inside your Zmacs buffer and the file 
itself is not really changed. 
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Creating a File 

The first time you save or write the buffer, Zmacs creates the new 
file. You can create a new file with c-X c-s. Since a new file does 
not have a name associated with it yet, Zmacs asks for a name for 
the new file. It offers a default pathname, which is the name of 
the buffer. If you wish to save the file out to the default 
pathname, simply type a return in response to the prompt. 

If you wish to save the buffer in another file, provide that name as 
your response. Completion is offered to simplify your response. 

You can also write the buffer out with c-X c-U, Write File. Zmacs 
prompts in the minibuffer for the name of the place you want to 
write the buffer's contents. c-X c-U also offers a default 
pathname, in this case, the name you supplied with c-X c-F. 

Editing Existing Files 

To tell Zmacs to edit text in a file, use c-X c-F, the Find File 
command, and give Zmacs a file name. You can enter the 
pathname of any file on any host that is reachable by network 
connections from your Lisp Machine. If the file already exists, 
Zmacs locates the file and reads it into your buffer. 
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Introduction 

The extended commands Format Region O-X) , Format Buffer 
(n-X) , and Format File (n-X) display text in a formatted style 
using formatting instructions that you embed in the text. You can 
send the formatted text to a Symbolics LGP-1 printer (no other 
printer is supported) by giving the Format command a numeric 
argument. 

Producing 
Formatted Text 

Producing formatted text requires two steps: 

1. Entering the text and formatting instructions 

2. Formatting that text with one of the Zmacs formatting 
commands 

First you use the Zmacs editor to enter the text and embed 
formatting instructions, which can be environments and commands. 
These instructions format the text by, for example, specifying fonts, 
creating bulletted lists, and inserting headings. 

For example, to specify that you want to italicize a group of words, 
like the title of a book, use the italicize environment. To 
emphasize a word, you might use the boldface environment. 

This text: 

@i(Gone With the Wind), by Margaret Mitchell, is a @b(great) book. 

produces this, when formatted: 

Gone With the Wind, by Margaret Mitchell, is a great book. 

Formatting instructions all begin with an @. The i tells the 
formatter that you want the italicize environment, and the 
parentheses (delimiters) enclose the text within that environment. 
Other valid delimiters can be [], o, {}, "", ", or ". 

How to Create an Environment 

Environments can be either short form, ei( italicize this), or long 
form, where the commands @begin(i) and @end(i) act as delimiters 
for the text that they enclose. For example, to italicize an entire 
passage: 

ebegin(i) 

Environments can be either short form or long form. The long 

form uses the commands eebegin and @@end to act as delimiters 

for the text that they enclose. 

@end(i) 

produces this: 
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Environments can be either short form or long form. The long form 
uses the commands ©begin and ©end to act as delimiters for the 
text that they enclose. 

(The @s inside the environment must be doubled so the formatter 
does not interpret them as format commands.) 

The following environment enumerates, that is, numbers 
sequentially each separate line of text within it: 

6begin( enumerate) 
Paragraph 1 

Paragraph 2 

Paragraph 3 
8end( enumerate) 

produces the following output: 

1. Paragraph 1 

2. Paragraph 2 

3. Paragraph 3 

Basic Text 

Formatting Environments 

Environments can be either filled or unfilled: 

Filled Fills each output line to capacity within the 

limits of the display. 

Unfilled Keeps output lines exactly as you entered them, 

as in an example. 

Basic formatting environments are: 

b Displays enclosed text in boldface. 

c Displays enclosed text in capital letters. 

center Centers each line in an unfilled environment. 

description Outdents paragraphs with single spacing and 

wider margins in a filled environment. 

display Displays enclosed text in Roman (default) 

typeface and widens both margins in an unfilled 
environment. 

enumerate Moves the left margin to the right, displaying a 

number in the left margin for each paragraph. 

equation Displays equations in an unfilled environment 
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example 

figure 

flushleft 

flushright 

format 



fullpagefigure 
fullpagetable 

g 
heading 

i 
itemize 

majorheading 

multiple 

outputexample 

P 
quotation 



using fixed-width typeface. It widens both 
margins. 

Displays examples in an unfilled environment 
using fixed-width typeface. It widens both 
margins. 

Displays figures in an unfilled environment using 
Roman (default) typeface with no changes to the 
margins. 

Displays unfilled text aligned at the left margin. 
It recognizes and includes leading spaces. 

Displays unfilled text aligned at the right margin. 
It ignores trailing spaces. 

Displays enclosed text in an unfilled environment 
using Roman (default) typeface with no changes 
to the margins. Any horizontal alignment that is 
needed should be done with tabbing commands 
(for example, @\ and @>). 

Displays figures in an unfilled environment using 
Roman (default) typeface with no changes to the 
margins. 

Displays tables in an unfilled environment using 
Roman (default) typeface with no changes to the 
margins. 

Displays enclosed text in Greek typeface. 

Centers each line in boldface type in an unfilled 
environment. 

Displays enclosed text in italics. 

Moves the left margin to the right, displaying a 
bullet in the left margin for each paragraph. 

Centers each line in boldface type in an unfilled 
environment. 

Keeps enclosed text together as a single item 
within itemize, enumerate, or description 
environments, regardless of intervening paragraph 
breaks. 

Displays typeout examples in an unfilled 
environment using fixed-width typeface. It 
widens the right margin. 

Displays enclosed text in bold italics. 

Displays enclosed text in a filled environment 
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using Roman (default) typeface. It widens both 
margins. 

r Displays enclosed text in Roman typeface. For 

example to override the default typeface of the 
italicize environment: 6I(The Iliad er[and] The 
Odyssey) produces The Iliad and The Odyssey. 

subheading Displays each line in boldface type in an unfilled 

environment flush to the left margin. 

table Displays tables in an unfilled environment using 

Roman (default) typeface with no changes to the 
margins. 

text Displays enclosed text in a filled environment. 

verbatim Displays enclosed text in an unfilled environment 

in fixed-width typeface with no changes to the 
margins. 

t Displays enclosed text in fixed-width typeface. 



How to Use 
Formatting Commands 

Formatting commands control the format of the text (such as blank 
spaces between lines, tab settings, line breaks) and whether the 
formatter centers the text or aligns it against one of the margins. 

For example: 

@i(Gone With the Wind), 8* by Margaret Mitchell @# is a eb(great) book. 



produces: 

Gone With the Wind, 
by Margaret Mitchell 



is a great book. 



The @* command forces a line break and the @# command leaves a 
blank em-space for a special character to be drawn in. 

Some commands, like the @* in the example, are complete by 
themselves. Others accept arguments, which must be enclosed in 
delimiters. There is no such thing as a long form for a command; 
you cannot say ebegin(blankspace) for example. 
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Basic Text 
Formatting Commands 

©blankspace 



On paper, leaves the specified amount of blank 

space on the page (for example, 

©blankspace(lline)). Distance can be specified 

with: 

in, inch, inches, " 

cm, centimeters 

mm, millimeters 

pt, pts, point, points 

pica, picas 

em, ems, quad, quads 

char, chars, character, characters, en, ens 

line, lines 

On the screen, display truncates the blank space 
to roughly one inch of vertical space. 

Creates a figure caption enclosed in square 
brackets, for example, use ecapt ion [This is the 
caption] to produce: [Figure Caption: This is 
the caption.] 

Puts in a parenthetical note. Does not create 
bottom-of-the-page footnotes or numbering. 

Puts in a parenthetical note. 

Clears all tabs. It takes no arguments: use 
etabclearO. 

Sets tabs to divide text into the specified number 
of columns, for example, @tabdivide(4) sets tabs 
to divide the following text into 4 columns across 
the page. 

Sets one or more tabs at specified positions. 

Distance can be specified with: 

in, inch, inches, " 

cm, centimeters 

mm, millimeters 

pt, pts, point, points 

pica, picas 

em, ems, quad, quads 

char, chars, character, characters, en, ens 

line, lines 



These punctuation-character commands consist of an © followed by 
one punctuation character. They take no arguments. 



©caption 



©foot 

©note 
©tabclear 

©tabdivide 



©tabset 
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@# Leaves a blank space (quad space or em-space) 

for a special character. 

@* Forces a line break. 

@. Generates a period and forces a single significant 

space after it (used for abbreviations). 

@= Sets a tab at the left side of text to be centered. 

Do not use in a filled environment. Works with 
the tab commands (@\, @>, or @=). 

@> Sets a tab at the left side of text to be flushed 

right. Do not use in a filled environment. 
Works with the tab command (@\, @>, or @=). 

@\ Moves the cursor to the next tab stop or marks 

the end of text being centered or flushed right. 
Do not use in a filled environment. 

@* Sets a tab at the current cursor position. Do not 

use in a filled environment. 

@@ Inserts an @ in the text. 

@" Ignores all the white space between it and the 

next text in the source. 



Example of Using 
Tabs to Format Text 

This example shows how to use tab stops to: 

• Divide text into four columns 

• Center text 

• Flush right text 

• Reset tabs 

8begin( format) 

6tabdivide(4) 

1.6\*8\*8\* 

2.8=a@\@=b@\8=c@\@=d 

3.8=e8=fe=ge=h 

4 . Lef te=Center8>r i ght 

5.Left8sCenter8>right8\ 

8tabclear() 

6.Left8sCenter8>right 

8end( format) 

produces: 
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1. 


# 




* 




* 






2. a 




b 




c 




d 




3. e 




f 




g 




h 




4.LeflCenter 














right 


5.LefCenter 






right 










6.Left 






Center 








right 



Zmacs Format Commands 

The second (and final) step in formatting is to issue one of the 
formatting commands, which interprets the text and formatting 
instructions into the formatted text. 



Format Region 



Format Buffer 



Format Region (m-x) 

Displays the contents of the region formatted as a text 
environment. With a numeric argument, it pops up a menu that 
asks whether you want to format the file on the screen or on the 
default printer. 



Format Buffer (n-X) 

Displays the contents of the buffer, formatted as a text 
environment. With a numeric argument, it pops up a menu that 
asks whether you want to format the file on the screen or on the 
default printer. 



Format File 



Format File (n-X) 

Displays the contents of the file, formatted as a text environment. 
With a numeric argument, it pops up a menu that asks whether 
you want to format the file on the screen or on the default printer. 
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Overview of 
Leaving Zmacs 

Use a system-wide command to switch programs, such as select, 
FUNCTION S, the System menu, or, if you have multiple windows on 
the screen, position the mouse to another window and click. 

Leaving Zmacs 
with the SELECT Key 

A set of windows is always available by pressing the select key and 

then one of the following keys: 

Key Program 

C Converse, for messages to other users 

D Document Examiner, for examining documentation 

E Editor, the Zmacs text and program editor 

F File system editor for access to files and directories 

I Inspector, for inspecting and modifying data structures 

L Lisp 

M Mail reading and sending system 

N Notifications, for rereading system notifications 

P Peek, a system status display 

T Telnet, a virtual terminal utility for logging in to other 

hosts 

X Flavor Examiner, for examining the structure of flavors 

that are defined in the Lisp environment 



Leaving Zmacs 

Via the System Menu 

The System menu is a momentary menu that lists several choices 
for acting upon windows and calling programs (for example, a Lisp 
Listener, Zmacs, or the Inspector). You can always call the System 
menu by clicking [(R2)] (the right mouse button twice or holding 
down the SHIFT key and clicking right once ). Use the System 
menu to do many things, among them: 

• Create new windows. 

• Select old windows. 

• Change the size and placement of windows on the screen. 

• Hardcopy a file. 

Leaving Zmacs 
with c-2 

The Zmacs command c-H returns you to the window in which the 
ed function was most recently called, usually the Lisp Listener. 
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Overview of 

Getting Out of Trouble 

Sometimes you type the wrong command. Mostly it is obvious 
what you have done wrong, and it is a simple matter to undo it. 
There are, however, some kinds of trouble you can get into that 
require special remedies. For example, you might accidentally delete 
large chunks of text you need or you might begin to type a 
command and then change your mind. 

This section tells you how to recover from these situations. 

Getting Out of 
Prefixes and Prompts 

Most of the commands we have described are single keystrokes, but 
some keystrokes are prefixes that must be completed with a second 
keystroke to specify a command, c-x is the most important of 
these. 

Getting Out of 

Keystroke Prefixes 

If you press a c-X and don't mean it, you can get out by pressing 
either c-G or rbort. These are general "get me out of here" 
commands, which you should use whenever you get yourself into a 
confused state. RBORT and c-G are, for the most part, synonymous 
in Zmacs. 

Getting Out of 

Minibuffer Prompts 

Sometimes you accidentally type a command that prompts for some 
additional information, or you type such a command on purpose and 
change your mind afterwards. When Zmacs prompts and you just 
want to get out of the minibuffer and back to where you were, 
press RBORT. If, instead, you wish to cancel and reenter your 
response, use c-G, which clears any typein but leaves you still in 
the minibuffer. When the minibuffer is empty, c-G cancels the 
minibuffer command. (With some echo area prompts, you have to 
use ABORT.) 

ABORT Abort At Top Level 

Cancels the last command typed. It also cancels numeric 
arguments and region marking. 

c-G Beep 

Cancels the last command. It also cancels numeric arguments and 
region marking, except when given an argument. It cancels one 
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thing at a time, so that if you've typed a number of commands or 
responses, you must use use successive c-Gs to cancel each one and 
return to top level. 

Large Deletions 

Do not delete large pieces of text by repeatedly pressing rubout and 
c-D. Apart from being slow, text deleted character-by-character is 
gone for good. 

Instead, use delete and kill commands that save deleted regions in 
the kill history. c-K, n-K, and the commands that deal with 
regions easily wipe out and save larger chunks. Also, rubout or c-D 
with a numeric argument erases that many characters all at once 
and saves them in the kill history. For full descriptions of these 
delete and kill commands: See the section "Deleting and 
Transposing Text in Zmacs", page 71. 

Getting Text Back 

The system has different histories for different contexts. One of 
these is always the current history. The two histories that you 
need to use for yanking in Zmacs are the kill history and the 
command history. The kill history remembers pieces of text that 
you killed or copied into it. In the context of Zmacs, the command 
history remembers all the editor commands that use the minibuffer 
in any way. 

Additions to the histories are placed at the top of the list, so that 
history elements are stored in reverse chronological order — the 
newer elements at the top of the history, the older elements toward 
the bottom. A history remembers everything that has been typed 
to it since the last cold boot — it has no size limit. 

Yanking commands pull in the elements of the history. Top-level 
commands start a yanking sequence; for example, c-Y yanks back 
the last text killed from the kill history, and c-n-Y yanks back the 
last command performed in the minibuffer. n-Y performs all 
subsequent yanks in the same sequence; for example, pressing n-Y 
while the kill history is the current history yanks the next item 
from that history. 

A yanking sequence ends when you type new text, execute a form 
or command, or start another yanking sequence. 

For complete descriptions of killing and* yanking: See the section 
"Working with Regions in Zmacs", page 85. 
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Overview of 
Finding Out 
About Zmacs Commands 

Sometimes you want to know if a Zmacs command exists that 
performs a certain function. Or, you might think that you know 
what a certain keystroke does, but you still want to make sure, or 
refresh your memory about its exact usage. This manual is one 
resource you might use in these circumstances. Zmacs itself has a 
number of built-in self-documentation facilities. This section 
describes some ways to get at this documentation. 

Finding Out 

About Zmacs 

Commands with HELP 

The help key is a prefix to a useful group of commands giving 
various kinds of online help. If you forget what a command does, 
which keystrokes perform an action, or have no idea how to 
accomplish something, press help. 

Whenever you have a question of any kind, press help. Zmacs 
prompts you in the minibuffer for details on what kind of help. If 
you don't know, press help again and it tells you, in the typeout 
window, how to find what you're looking for. The typeout window 
displays right over the editor window. The actual contents of the 
buffer are not affected, and the next command you type restores 
the buffer display. 

Finding Out What 
a Zmacs 
Command Does 

HELP C 

The command HELP C displays "Document Command:" below the 
mode line and waits for you to type a command. When you do, 
Zmacs displays the internal documentation for that command. 



Example 



If you press HELP-C followed by c-F, the response is: 

c-F is Forward, implemented by COM-FORWARD: 

Moves forward one character. 

With a numeric argument (n), it moves forward n characters. 

The first line above tells you the name of the command (in this 
case Forward), and the name of the internal Lisp function that 
actually does the work (in this case com-forward). (You don't 
need to know these internal names for basic editing.) The COH-xxx 
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name displayed by HELP C is mouse-sensitive: clicking left on it 
edits the COM-xxx function, and clicking right displays a menu with 
choices of Arglist, Edit, Disassemble, and Documentation. 

The next line is a very short description of what the command 
does; it usually tells you what the command does without a 
numeric argument and how a numeric argument modifies that 
behavior. 

Finding Out What a 

Prefix Command Does 

When you ask (with help c) for documentation on a prefix 
command like c-x, Zmacs prompts you, in the typeout window, to 
complete the command. Zmacs displays the documentation for the 
prefix command in the typeout window. 



Finding Out What 
an Extended 
Command Does 



HELP D 



When you want to find out what an extended command does, you 
can display the documentation for the command by pressing help d, 
which prompts in the minibuffer "Describe command:", to which 
you type the command's name. 

Searching for 
Appropriate 
Zmacs Commands 

help n 

When you can only guess at part of the name of a command by 
the action it performs, there is a command, HELP fi, to help you 
scan all the available Zmacs commands to find the one you want. 

Each Zmacs command has a name. The name is almost always 
exactly what you would expect; that is, the name describes the 
function of the command in reasonably plain English. 

Method for 

Searching for 

Appropriate Zmacs Commands 

To find the command you want, just press HELP fi. Zmacs prompts 
you for a substring, you enter your guess, and then Zmacs displays 
short descriptions of all the commands whose names contain that 
substring. If the string that you enter contains a space, then 
Zmacs displays a short description of all the commands whose 
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names include a similarly positioned space. Each description gives 
the short documentation for the command and tells what 
keystrokes invoke it. 

Example of a Search 

String for HELP fl 

The command you perform when you use n-Q is called "Fill 
Paragraph", so you might expect a command that counts the 
number of paragraphs in the buffer to be called something like 
"Count Paragraphs" or "Paragraphs Count". No matter what, the 
name is going to have the word paragraph in it. 

Finding Out What 
You Have Typed 

HELP L 

As you are editing you might find yourself in a hopelessly confused 
state and not know how to recover. 

If this happens to you it is often very enlightening to press help l 
to list the last 60 keystrokes you typed. By examining your own 
recent activity, it is often possible to find out where you went 
wrong and how to save yourself. 

More HELP 
Commands for 
Finding Out 
About Zmacs Commands 

HELP U 

Offers to undo the last "major" operation (such as fill or sort). 

HELP V 

Displays all the Zmacs variables whose names contain a certain 
substring. For descriptions of Zmacs variables: See the section 
"How to Specify Zmacs Variable Settings", page 210. 

HELP u 

Finds out whether an extended command is bound to a key. 

General 

Information-giving 
Zmacs Commands 

The following commands display: 

• Information about the location of point 
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• Documentation about a specified Lisp function 

• Argument list for the specified Lisp function 

• Information about the current Lisp variable 

• The number of lines in the region or page 

• Possible parenthesis mismatches 

• Trace information about the specified Lisp function 

The word current, when describing a Lisp function or a Lisp 
variable, refers to (approximately) the function or variable whose 
name is nearest to the cursor. 

c-X = Where Am I 

Displays various things about the location of point. It displays the 
X and Y positions, the octal code for the following character, the 
current line number and its percentage of the total file size. If 
there is a region, it displays the number of lines in it. Fast Where 
Am I (c-=) displays a subset of this information more quickly. 

c-= Fast Where Am I 

Quickly displays various things about where point is. It displays the 
X and Y positions and the octal code for the following character. If 
there is a region, it displays the number of lines in it. Where Am I 
displays the same things and more. 

n-sh-D Show Documentation 

Displays the documentation for the given topic. It prompts for a 
topic name offering completion only on topics in the documentation 
database. With a numeric argument, n-sh-D directs the display to 
either the screen or paper (hardcopy). 

See the section "The Document Examiner" in User's Guide to 
Symbolics Computers. 

c-sh-D Long Documentation 

Displays the documentation string for the specified function. It 
prompts for a function name, which you can either type in or select 
with the mouse. The default is the current function. 

When this command does not find a documentation string, it 
suggests you use Show Documentation (n-x) or the Document 
Examiner to see the function's online documentation. 

c-sh-fi Quick Arglist 

Displays the argument list for the current function. With a 
numeric argument, it reads the function name from the minibuffer. 
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Arglist (n-X) 

Displays the argument list of the specified function. It reads the 
name of the function (from the minibuffer) and displays the 
argument list in the echo area. 

c-sh-v Describe Variable At Point 

Displays information in the echo area about the current Lisp 
variable. The information displayed shows whether it is declared 
special, whether it has a value, and whether it has documentation 
put on by defvar. When nothing is available, it checks for 
lookalike symbols in other packages. 

n-= Count Lines Region 

Displays the number of lines in the region. 

c-x L Count Lines Page 

Displays the number of lines on the current page (or the buffer, if 
there are no page delimiters). In parentheses, it displays the 
number of lines up to the line containing point and the number of 
lines after the line containing point. 

Find Unbalanced Parentheses (m-X) 

Finds any parenthesis mismatch error in the buffer. It reads 
through all of the current buffer and tries to find places in which 
the parentheses do not balance. It positions point to possible 
trouble spots, printing out a message that says what the trouble 
appears to be. This command finds only one such error; if you 
suspect more errors, run it again. 

Trace (n-X) 

Traces or untraces a function. It reads the name of the function 
from the minibuffer and then it pops up a menu of trace options. 
With an argument, it omits the menu step. 
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Overview of the 
Editor Menu 



Click right in Zmacs to display the editor menu, a momentary menu 
containing editor commands, each of which is a possible choice. 
Position the mouse cursor over an item and then click the 
appropriate button to make the choice. 



For complete descriptions of the editor menu commands: 
section "Editor Menu Commands", page 49. 



See the 



Editor Menu Commands 

The Editor Menu commands are: 



Command 
Arglist 



Edit Definition 



List Callers 



List Definitions 



List Buffers 



Kill Or Save Buffers 



Split Screen 



Description 

Prints the argument list of the 
specified function: See the section 
"General Information-giving Zmacs 
Commands", page 46. 

Prepares to edit the definition of a 
specified function: See the section 
"Editing Lisp Programs in Zmacs", 
page 169. 

Lists all functions that call the 
specified function: See the section 
"Editing Lisp Programs in Zmacs", 
page 169. 

Displays the definitions in a specified 
buffer: See the section "Editing Lisp 
Programs in Zmacs", page 169. 

Prints a list of all the buffers and 
their associated files: See the section 
"Manipulating Buffers and Files in 
Zmacs", page 113. 

Offers a menu of modified files with 
choices to kill, save, or remove the 
modification flag from the file: See the 
section "Manipulating Buffers and 
Files in Zmacs", page 113. 

Makes several windows split among 
the buffers as specified: See the 
section "Manipulating Buffers and 
Files in Zmacs", page 113. 
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Compile Region 

Indent Region 
Change Default Font 
Change Font Region 
Uppercase Region 

Lowercase Region 

Indent Rigidly 
Indent Under 



Compiles the region, or if no region is 
defined, the current definition: See the 
section "Editing Lisp Programs in 
Zmacs", page 169. 

Indents each line in the region: See 
the section "Changing Case and 
Indentation in Zmacs", page 159. 

Sets the default font: See the section 
"Working with Regions in Zmacs", 
page 85. 

Changes the font for the region: See 
the section "Working with Regions in 
Zmacs", page 85. 

Changes any lowercase characters in 
the region to uppercase: See the 
section "Working with Regions in 
Zmacs", page 85. 

Changes any uppercase characters in 
the region to lowercase: See the 
section "Working with Regions in 
Zmacs", page 85. 

Shifts text in the region sideways as a 
unit: See the section "Changing Case 
and Indentation in Zmacs", page 159. 

Fixes indentation to align under either 
a character that you click on with the 
mouse cursor or a string read from 
the minibuffer: See the section 
"Aligning Indentation in Zmacs", page 
165. 
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Minibuffer 
Response Format 

Most commands expect only one line of response. In these cases, 
the end key has the same meaning as the RETURN key, terminating 
the response. 

However, for commands that expect one or more lines of response, 
RETURN has its usual significance, inserting a newline in the 
minibuffer, and END marks the end of the response. 

Minibuffer 
Response Help 

While responding to a prompt, you can press HELP to get 
documentation describing the current situation. Zmacs tells you 
exactly what input it expects and what the possible responses are. 

More Ways to 

Enter Minibuffer Responses 

Yanking and mousing provide quick and simple ways to enter 
minibuffer responses without having to type them out. Both of 
these methods are context-sensitive. Yanking works only when you 
have previously entered a minibuffer response. Mousing works 
when you click on a name that makes sense in the context of the 
minibuffer prompt. 

Yanking in the Minibuffer 

c-n-Y Repeat Last Minibuffer Command 

Repeats a recent minibuffer command. It yanks the displayed 
default if there is one, otherwise, it yanks the last thing typed in 
this context. A numeric argument n yanks the nth previous one. 
An argument of lists the history of elements typed in the 
minibuffer. 

After c-n-Y, n-Y replaces what was yanked with a previous element 
of the same history, in this case, another minibuffer command. 
For more details: See the section "Retrieving History Elements", 
page 74. 

n-Y Yank Pop 

Corrects a yank to use a different element of its history. The most 
recent command must be a yanking command (c-Y, n-Y, or c-n-Y). 
The retrieved text that was yanked by that command is replaced by 
the previous element of the relevant history. The history is rotated 
(that is, the elements remain in the same order, but the pointer to 
the current element moves with each successive n-Y) to bring this 
element to the top. 
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A numeric argument of zero displays the history. A positive 
numeric argument of n moves n elements back in the history list. 
A negative numeric argument moves to a newer history element; 
this only makes sense after you rotate the history. 
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Overview of Moving the Cursor 



Summary of 
Cursor Movement 

To make changes at a particular place in a Zmacs buffer, you must 
move the cursor to that place, since most commands that modify 
the buffer do so immediately around the cursor. 

The cursor movement or motion commands: 

• View the contents of the buffer 

• Redisplay the editor window 

• Move the cursor around the buffer using mouse commands 

• Move the cursor around the buffer using keystroke commands 

The Editor 

Window and the Buffer 

The editor window displays either a portion of your buffer or the 
whole buffer, depending on the size of the buffer and your current 
location in it. 

When the current buffer is smaller than the exact size of the editor 
window, Zmacs displays the contents of the buffer at the top of the 
window and leaves the bottom of the window blank. You cannot 
tell whether the buffer actually comes to an end where the text 
stops, since there could be white space and newline characters after 
the last visible piece of text. 

When the buffer is too large to fit on the screen, the editor window 
shows only a section of the buffer. The part that shows always 
contains the cursor, so it never vanishes off the top or bottom of 
the editor window. Zmacs changes the position of the editor 
window inside the buffer as seldom as possible — usually only when 
you try to move the cursor off the top or bottom of the screen. 

Wraparound Lines 

in the Editor Window 

Lines that are too long to fit across the editor window are displayed 
on as many physical lines as are necessary. An exclamation point 
(!) in the (normally blank) last column means that the next 
physical line is part of the same logical line. 
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Introduction to 
Redisplaying the Window 

Whenever you modify the buffer's contents or move point or the 
mark, Zmacs updates the display to reflect the change. (For a 
discussion of the mark: See the section "Working with Regions in 
Zmacs", page 85.) This updating can be as simple as moving the 
cursor or as involved as figuring out the whole display from scratch. 
These operations are called redisplay and Zmacs performs them 
automatically. 

For example, when you move the cursor off the top or bottom of 
the editor window, a complete redisplay is required. The window 
has to shift to show a different part of the buffer in order to keep 
the cursor visible. 

You can explicitly tell Zmacs to do a redisplay with the Recenter 
Window command, invoked by c-L. You might want to do this if 
the cursor gets too close to the top or the bottom of the editor 
window, and you want to redisplay with the cursor closer to the 
center so that you can see more context in one direction or the 
other. 

It is important to remember that redisplay operations change only 
the display, not the actual contents of the buffer. 

Recentering the Window 

c-L Recenter Window 

Completely redisplays the screen, leaving the cursor near the middle 
of the editor window. 

With a numeric argument of n y it leaves the cursor n lines from 
the top of the window. With a negative numeric argument of -n y it 
leaves the cursor n lines from the bottom of the window. 



Displaying the 
Next Screen 



c-V, SCROLL Next Screen 

Moves the cursor to the beginning of the last visible line in the 
editor window and redisplays the screen with that line at the top of 
the window. 

With a numeric argument of n, it moves the text up n lines. With 
a negative numeric argument -n, it moves the text down n lines. 
The cursor does not move (with respect to the text) unless the 
numeric argument is large enough to slide it off the screen. In 
that case the cursor remains at the top. 
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Displaying the 
Previous Screen 

n-y, n-SCROLL Previous Screen 

Moves the cursor to the beginning of the first visible line in the 
editor window and redisplays the screen with that line at the 
bottom of the window. 

With a numeric argument of n, it moves the text down n lines. 
With a negative numeric argument -n, it moves the text up n lines. 
The cursor does not move (with respect to the text) unless the 
numeric argument is large enough to slide it off the screen. In 
that case the cursor remains at the bottom. 

Positioning the 

Window Around a Definition 

c-n-R Reposition Window 

Redisplays, trying to get all of the current function definition in the 
window. It puts the beginning of the current definition at the top 
of the window with the current position of the cursor still visible. 
Doing c-n-R twice pushes comments off the top of the window, 
making more of the code of a large function visible. 



Moving to a 
Specified Line 



m-r Move To Screen Edge 

Moves to the beginning of a specified line on the screen. With no 
argument, it moves to the beginning of a line near the middle of 
the screen. The exact line is controlled by the Zmacs variable 
Center Fraction. A numeric argument specifies a particular line to 
move to. Negative arguments count up from the bottom of the 
window. (For descriptions of Zmacs variables: See the section 
"How to Specify Zmacs Variable Settings", page 210.) 
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Introduction to 
Using the Mouse 

The easiest way to get the cursor where you want it is with the 
mouse. See the section "The Mouse" in User's Guide to Symbolics 
Computers. 



Mouse 

Documentation 
Line in Zmacs 



The mouse documentation line: 

• Appears just above the bottom line of the screen 

• Normally stands out in reverse video 

• Contains documentation on the current meaning of mouse clicks 

In a regular Zmacs buffer, the mouse documentation line offers the 
following options: 



Notation 
L:Move point 



L2:Move to point 
M:Mark thing 



Description 

Performs two separate actions: 

• Relocates the cursor: position the mouse 
cursor to the desired location and click left. 

• Makes a region: position mouse cursor to 
desired location, click left (keeping the 
button down), move mouse cursor to end of 
region and lift the button up. 

Relocates the mouse cursor near the cursor: 
click left twice. 

Marks (makes into a region) the object on 
which you click. Clicking after the end of a 
line or before the first nonblank character of 
a line marks the whole line. Clicking on a 
word marks that word, as delimited by 
nonalphanumeric characters. 

In Lisp mode, however, if that word is part of 
what could be a symbol's printname, it marks 
that whole symbol name. Clicking on an 
open or close parenthesis marks all the text 
between that parenthesis and its matching 
parenthesis, including the parentheses. 
Clicking on an open or close quotation mark 
(") marks the whole quoted string. Clicking 
between words marks all text up to the end 
of the next word or possible symbol 
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c-M:Copy Mouse 



printname, depending on mode. (For a 
complete description of marking regions: See 
the section "Working with Regions in Zmacs", 
page 85. 

Inserts the object on which you click, as 
though you had typed it. This allows you to 
build a program or document by selecting 
things already appearing on your screen, in 
the manner of a menu. Hold down the 
control key and click middle on the object you 
want to copy: it is inserted as though you 
had just typed it. If you change your mind, 
and want to remove what you have just 
inserted, type c-U, and it is removed. 

The object to be copied can be a word, a 
printed representation of a Lisp symbol, a 
parenthesized or quoted group of words, a 
printed representation of a lisp list or string, 
or a line. What object is picked up by 
clicking c-(M) on it is determined by the 
same rules as Mark Thing (M) in Lisp Mode. 
That is: 

• Clicking after the end of a line or before 
the first nonblank character of a line copies 
the whole line. Clicking on a word picks 
up that whole word, or possible Lisp 
Symbol printname of which that word could 
be part. 

• Clicking on an open or close parenthesis 
copies the text between that parenthesis 
and its matching parenthesis, including the 
parentheses. Clicking on an open or close 
quotation mark (") copies the whole quoted 
string. Clicking between words copies all 
text up to the end of the next word (or 
possible symbol printname). 

Appropriate spaces are put before the inserted 
object, if needed. 

M2:Save/Kill/Yank Performs one of four related actions: 

• If there is a region, it saves the region in 
the kill history while leaving it in the 
buffer (like n-U) 

• If the last command saved the region, it 
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wipes it from the buffer (like c-W except it 
does not save) 

• If the above two conditions do not apply, it 
yanks the first element from the kill 
history (like c-Y) 

• If the last command was a yank command, 
it yanks the next item from the kill history 
(like n-Y) 

(For a complete description of saving, killing, 
and yanking regions: See the section 
"Working with Regions in Zmacs", page 85. 

RrMenu Displays a Zmacs menu offering mouse- 

sensitive Zmacs commands. 

R2:System Menu Displays a System menu. 
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Introduction to 

the Motion Commands 

Zmacs word, sentence, and paragraph motion commands all have 
strict definitions for where words, sentences, and paragraphs begin 
and end. You can modify all these definitions. 

Numeric 

Arguments and 

the Motion Commands 

All of the motion commands allow numeric arguments. For the 
most part, these numeric arguments are interpreted as repeat 
counts. 

Example of Numeric 
Arguments with 
Motion Commands 

n-F moves the cursor forward one word, whereas n-l3F moves the 

cursor forward 13 words. 

Negative Numeric 

Arguments and 

Motion Commands 

Most of the motion commands come in pairs, with one command 
for forward motion over a particular unit and one command for 
backward motion. Both kinds of commands often interpret negative 
numeric arguments by reversing the direction of motion. 

These conventions — that Zmacs interprets numeric arguments as 
repeat counts, and that negative numeric arguments reverse the 
direction of motion — together make up the motion convention. 

Example of Negative 
Numeric Arguments 
with Motion Commands 

n — 13F moves point backward 13 words. n-l3B has exactly the 

same effect. 

Motion by Character 

A Zmacs character can be any letter, number, or punctuation 
character. 
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Forward Character 

c-F Forward 

Moves the cursor forward over one character. c-F interprets 
numeric arguments as repeat counts. 

Negative numeric arguments reverse the direction of motion. For 
example, c-3B and c — 3F both move the cursor backwards three 
characters. 

Backward Character 

c-B Backward 

Moves the cursor backward over one character. c-B interprets 
numeric arguments as repeat counts. 

Negative numeric arguments reverse the direction of motion. For 
example, c-3 c-B and c — c-3 c-F both move the cursor backwards 
three characters. 

Motion by Word 

Zmacs generally considers a word to consist of a sequential string of 
alphanumeric characters, that is, any combination of the characters 
a-z, A-Z, and 0-9. Different major modes define their own delimiter 
characters. For example, in Text Mode an apostrophe (') is part of 
a word, but in other modes it is a delimiter. (For mode 
descriptions: See the section "Setting the Zmacs Major Mode", page 
155.) 



Forward Word 



Backward Word 



n-F Forward Word 

Moves the cursor forward one word. Numeric arguments are 
interpreted as repeat counts; negative numeric arguments reverse 
the direction of motion. 

n-F always places the cursor at the end of a word. If the cursor is 
in the middle of a word, n-F moves the cursor to the end of that 
word. 



n-B Backward Word 

Moves the cursor backward one word. Numeric arguments are 
interpreted as repeat counts; negative numeric arguments reverse 
the direction of motion. 

n-B always places the cursor at the beginning of a word. If the 
cursor is in the middle of a word, n-B moves the cursor to the 
beginning of that word. 
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Motion by Sentence 



Description of Zmacs Sentence Delimiters 

According to Zmacs, sentences can end with question marks, 
periods, and exclamation points. Furthermore, these punctuation 
marks only end a sentence when followed by: 

• A newline 

• A space followed by either a newline or another space. 

However, Zmacs allows any number of closing characters, which are 
", ', ), and ], between the sentence-ending punctuation and the 
white space that follows it. A sentence also starts after a blank 
line. 

This corresponds closely to standard typing conventions. Zmacs 
does not recognize a period followed by one space as the end of a 
sentence, for example, as in "e.g. " or "Dr. ". 

Forward Sentence 

n-E Forward Sentence 

Moves the cursor forward one sentence. 

Numeric arguments are interpreted as repeat counts; negative 
numeric arguments reverse the direction of motion. 

n-E always places the cursor at the end of a sentence. If the 
cursor is in the middle of a sentence, n-E moves the cursor to the 
end of that sentence. 

Backward Sentence 

n-R Backward Sentence 

Moves the cursor backward one sentence. 

Numeric arguments are interpreted as repeat counts; negative 
numeric arguments reverse the direction of motion. 

n-fl always places the cursor at the beginning of a sentence. If the 
cursor is in the middle of a sentence, n-fl moves the cursor to the 
beginning of that sentence. 
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Motion by Line 

Lines are delimited by special characters called newlines. 



Down Line 



c-N Down Real Line 

Moves the cursor straight down to the corresponding column of the 
next line. If the cursor is positioned in the middle of the line, c-N 
moves it to the middle of the next one. 

With a numeric argument n> it moves the cursor down n lines. 
Moving down a negative number of lines is the same as moving up. 

Up Line 

c-P Up Real Line 

Moves the cursor straight up to the corresponding column of the 
previous line. If the cursor is positioned in the middle of the line, 
c-P moves it to the middle of the previous one. 

With a numeric argument of n, it moves the cursor up n lines. 
Moving up a negative number of lines is the same as moving down. 

Beginning of Line 

c-ft Beginning of Line 

Moves the cursor to the beginning of the current line. 

With a numeric argument of n y it moves the cursor to the 
beginning of the nth line after the current one, where the current 
line is numbered 1, the preceding line is numbered 0, and so on. 

End of Line 

c-E End Of Line 

Moves the cursor to the end of the current line. 

With a numeric argument of rc, it moves the cursor to the end of 
the nth line after the current one, where the current line is 
numbered 1, the preceding line is numbered 0, and so on. 

Goal Column and 
the Motion Commands 

Set Goal Column 

c-X c-N Set Goal Column 

Sets the default column position (goal column). The goal column 
sets point position for c-N and c-P. It disables the default action of 
matching the goal column to point's current column and sets the 
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goal column to zero instead. With a numeric argument n, sets the 
goal column to n. c-u turns it off (sets it back to the default state 
of keeping cursor in same horizontal position for c-N and c-P). 
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Description 

Motion by Lisp expression repositions the cursor according to Lisp 
code delimiters: lists and expressions. A list is something enclosed 
in balanced parentheses. A Lisp expression is any readable printed 
representation of a Lisp object. 

c-n-N Forward List 

Moves forward over one list. It accepts a numeric argument for 
repetition count. 

c-n-P Backward List 

Moves backward over one list. It accepts a numeric argument for 
repetition count. 

Motion Along One 
Nesting Level 

Point always sits either between two expressions or in the middle of 
a Lisp object (excluding a list or nil). 

c-n-F Forward Sexp 

Moves point to the end of a surrounding Lisp object (excluding a 
list or nil) if there is one, or past the Lisp expression immediately 
to the right if not. 

If parentheses are unbalanced to such an extent that it doesn't 
make sense to talk about "the expression on the right", this 
command gives an error message and does not move point at all. 

c-n-F observes the motion convention for numeric arguments. 

c-n-B Backward Sexp 

Moves point to the beginning of a surrounding Lisp object 
(excluding a list or nil) if there is one, or to the beginning of the 
Lisp expression immediately to the left if not. 

If parentheses are unbalanced to such an extent that it doesn't 
make sense to talk about "the expression on the left", this 
command gives an error message and does not move point at all. 

c-n-B observes the motion convention for numeric arguments. 
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Motion up and 
Down Nesting Levels 

c-n-D Down List 

Moves point forward past any intervening Lisp object (excluding a 
list or nil) to the level of list structure and leaves point just to the 
right of the open parenthesis of that expression. 

With a numeric argument of n> it moves down n nesting levels. 
c-m-U Backward Up List 

Backs up out of nesting levels. It moves backward one level of list 
structure. It searches for an open parenthesis and leaves point to 
the left of that open parenthesis. Also, if called inside of a string, 
it moves back up out of that string, leaving point to the left of its 
starting quote. It accepts numeric arguments for repetition count. 

With a numeric argument of n, it moves up n nesting levels. 

c-m-) Forward Up List 

Moves forward out of nesting levels. It moves forward one level of 
list structure. It searches for a close parenthesis and leaves point 
to the right of that close parenthesis. Also, if called inside of a 
string, it moves up out of that string, leaving point to the right of 
its ending quote. It accepts numeric arguments for repetition 
count. 

With a numeric argument of n, it moves up n nesting levels. 

Motion Among 
Top-level Expressions 

A Lisp file contains a sequence of expressions that we call top-level 
expressions, to distinguish them from their own subexpressions. 
Zmacs assumes that top-level expressions begin with an open 
parenthesis against the left margin. It does not parse top-level 
expressions by balancing parentheses, since parentheses do not 
always balance while programs are being written. The indentation 
represents the programmer's conception of program structure, and 
provides a better guide. So by top-level expression, we mean a 
section of text delimited by open parentheses at the beginning of 
two lines. 

In code that includes a string containing a carriage return followed 
by an open parenthesis, show that the open parenthesis does not 
start a top-level expression by putting a slash in front of it. 
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c-n-R Beginning Of Definition 

c-n-[ 

Moves point to the beginning of the current top-level expression. 

With a positive numeric argument n, it moves back n top-level 
expressions. With a negative numeric argument -n, it moves 
forward n top-level expressions. 

c-m-E End Of Definition 

c-n-] 

Moves point to the end of the current top-level expression. 

With a positive numeric argument n, it moves forward n top-level 
expressions. With a negative numeric argument -n y it moves back 
n top-level expressions. 

m-) Move Over ) 

Moves past the next close parenthesis, then does Indent New Line. 
It removes any whitespace between point and the close parenthesis 
before moving over it. With a positive argument n f after finding 
the next close parenthesis and deleting whitespace before it, it 
moves past ti-1 additional close parentheses before doing Indent 
New Line. It ignores numeric arguments that are less than 1. 
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Introduction 

A paragraph is delimited by: 

• A newline followed by blanks (spaces or tabs) 

• A blank line 

• A Page character alone on a line 

• Various other mode-dependent factors (for example, a line that 
does not begin with the fill-prefix). See the section "Filling a 
Region", page 94. 

Forward Paragraph 

n-] Forward Paragraph 

Moves the cursor forward one paragraph. 

Numeric arguments are interpreted as repeat counts; negative 
numeric arguments reverse the direction of motion. 

n-1 always places the cursor at the end of a paragraph. If the 
cursor is in the middle of a paragraph, n-] moves the cursor to the 
end of that paragraph. 

Backward Paragraph 

n-[ Backward Paragraph 

Moves the cursor one paragraph backward. 

Numeric arguments are interpreted as repeat counts; negative 
numeric arguments reverse the direction of motion. 

n- [ always places the cursor at the beginning of a paragraph. If 
the cursor is in the middle of a paragraph, n- [ moves the cursor to 
the beginning of that paragraph. 
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Motion by Page 



Introduction 



Pages are delimited by Page characters. You can insert a Page 
character by pressing the PAGE key. The Page delimiter belongs to 
the page that precedes it and is therefore the last character on that 
page. 



Forward Page 



c-X ] Next Page 

Moves the cursor to the beginning of the next page; that is, puts 
the cursor immediately after the nearest following Page delimiter. 
If the buffer does not contain a Page delimiter, it goes to the end 
of the buffer. 

With a positive numeric argument n, it repeats this operation n 
times to move forward n pages. A negative numeric argument -n 
moves the cursor backward instead. 

c-X [ always places the cursor immediately to the right of the next 
Page delimiter. If the cursor is immediately to the left of the Page 
delimiter, c-X ] goes to the beginning of the page after next rather 
than just moving forward one character. 

Backward Page 

c-X [ Previous Page 

Moves the cursor to the beginning of the previous page; that is, 
puts the cursor immediately after the nearest preceding Page 
delimiter. If the buffer does not contain a Page delimiter, it goes 
to the beginning of the buffer. 

With a positive numeric argument n, it repeats this operation n 
times to move backward n pages. A negative numeric argument -n 
moves the cursor forward instead. 

c-X [ always places the cursor at the beginning of a page. If the 
cursor is already at the beginning of the page, c-x [ moves it to 
the beginning of the previous page. 
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Beginning/End of Buffer 

n-< Goto Beginning 

Moves the cursor to the beginning of the buffer. 

With a numeric argument n between and 10, it moves the cursor 
to a place rc/10 of the way (counted in lines) from the beginning of 
the buffer towards the end. 

m-> Goto End 

Moves the cursor to the end of the buffer. You can use n-> if you 
are in doubt as to the exact place on the screen where the buffer 
stops. 

With a numeric argument n between and 10, it moves the cursor 
to a place ti/10 of the way (counted in lines) from the end of the 
buffer towards the beginning. 
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Deleting Vs. Killing Text 



Overview 



Deleting text merely gets rid of it, but Zmacs deletion commands 
not only kill text but also get it back. These commands save killed 
text in a history stack. Other commands, called yanking 
commands, retrieve elements from the history. 

Deletion commands that operate on single characters do not save 
what they delete. However, by giving them a numeric argument, 
thus telling them to delete several characters, they too save the 
deleted text. 

The commands that delete white space only do not save it. 



What Histories Save 

Zmacs uses several histories: 



Type Description 

Kill History of text deleted or saved. The kill history 

is shared with the input editor, thus allowing you 
to move text between files and the Lisp Listener. 

Replace History of arguments to Query Replace (n-x) and 

related commands. See the section "Searching, 
Replacing, and Sorting in Zmacs", page 97. 

Buffer History of editor buffers visited in this window. 

See the section "Manipulating Buffers and Files 
in Zmacs", page 113. 

Pathname History of file names that have been typed. 

Command History of editor commands that use the 

minibuffer, and their arguments. Commands 
that do not use the minibuffer, for example, 
n-RUBOUT, are not recorded in the history. 

Definition History of names of definitions that have been 

typed. 

History lengths are limitless but the typeout window displays only 
the first 25 elements of the history. When the history contains 
more than 25 elements, the screen displays a mouse-sensitive line: 
n more elements in history. Clicking left displays the rest of the 
history. 

Only a single instance of each of these histories exists, shared 
among all editors, including Zmacs, Zmail, and Dired. 
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Kill History 



The kill history contains deleted text and is the history that saves 
the results of the commands described in this chapter. It allows 
you to move text from one editor window to another, for example, 
from the editor to a Lisp Listener. The yanking commands 
described below retrieve elements from the kill history. 



Viewing the Kill History 

c-e c-y 



Displays the elements of the kill history (saved text) in a typeout 
window: 

Kill history: 

1: last piece of killed text 

2: next-to-last piece of killed text 

3: this one is a very long piece of killed text... 



(End of history.) 



Viewing the 

Editor Command History 

c-0 c-n-Y 



Displays the elements of the editor command history (commands 
typed) in a typeout window: 

Command history: 

1: Control-X Control-F last-file-read-in 

2: Help A 

3: Control -X Control-F other-file-read-in 



(End of history.) 

This command is context-sensitive. When typed at the Lisp 
Listener level, it lists the recent commands typed there. When 
typed at the minibuffer, it lists the history appropriate to what is 
being read in the minibuffer, for example, a pathname or the name 
of a definition. 
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Using the Mouse 
on History Elements 

History elements are mouse-sensitive. Click on an element of the 
kill history to yank it to point; click on an element of the command 
history to reexecute it. 

Retrieving History Elements 

c-Y Yank 

Yanks back and inserts the last text killed or saved. If you have 
moved point since you killed the text, put point where you want 
the killed text to go before pressing c-Y. Point ends up after the 
text, and mark before the text. An argument of c-u puts point 
before the text instead. A numeric argument of zero displays the 
kill history and does not yank anything. A nonzero numeric 
argument selects an element of the kill history. 

c-m-Y Repeat Last Minibuffer Command 

Repeats a recent minibuffer command. It yanks the displayed 
default if there is one, otherwise, it yanks the last thing typed in 
this context. A numeric argument n yanks the nth previous one. 
An argument of lists the history of elements typed in the 
minibuffer. 



• After c-m-y, m-Y replaces what was yanked with a previous 
element of the same history, in this case, another minibuffer 
command. 

• After c-Y, m-Y replaces what was yanked with a previous element 
of the same history, in this case, the previous saved text. 

m-Y Yank Pop 

Corrects a yank to use a different element of its history. The most 
recent command must be a yanking command (c-Y, m-y, or c-n-Y). 
The retrieved text that was yanked by that command is replaced by 
the previous element of the relevant history. The history is rotated 
(that is, the elements remain in the same order, but the pointer to 
the current element moves with each successive n-Y) to bring this 
element to the top. 

A numeric argument of zero displays the history. A positive 
numeric argument of n moves n elements back in the history list. 
A negative numeric argument moves to a newer history element; 
this only makes sense after you rotate the history. 
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Kill Merging 



Normally, each kill command pushes a new block onto the kill 
history. However, two or more kill commands in a row combine 
their text into a single element on the history, so that a single c-Y 
command gets it all back as it was before it was killed. This means 
that you do not have to kill all the text in one command; you can 
keep killing line after line, or word after word, until you have killed 
it all, and you can still get it all back at once. 

Commands that kill forward from point add onto the end of the 
previous killed text. Commands that kill backward from point add 
onto the beginning. This way, any sequence of mixed forward and 
backward kill commands puts all the killed text into one element 
without rearrangement. 

If a kill command is separated from the last kill command by other 
commands, it starts a new element on the kill history, unless you 
tell it not to by saying c-n-W (Append Next Kill) in front of it. The 
c-n-U tells the following command, if it is a kill command, to 
append the text it kills to the last killed text, instead of starting a 
new element. With c-n-U, you can kill several discrete pieces of 
text and accumulate them to be yanked back in one place. 

c-n-u Append Next Kill 

Makes the next kill command append text to the newest element of 
the kill history. 
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Deleting the Last Character 

RUBOUT Rubout 

Deletes the character immediately to the left of the cursor. 

If the cursor is at the beginning of a line, RUBOUT deletes the 
newline character at the end of the previous line, thus appending 
the current line to the previous one. 

With a positive numeric argument of n, RUBOUT deletes the n 
characters immediately to the left of the cursor. With a negative 
numeric argument of -n, it deletes the n characters immediately to 
the right of the cursor. With any numeric argument, it saves the 
deleted characters on the kill history. 

Deleting the 
Current Character 

c-D Delete Forward 

Deletes the character at the cursor. 

If the cursor is at the end of a line, c-D deletes the newline 
character at the end of the line, thus appending the next line to 
the current one. 

With a positive numeric argument of n, c-D deletes the n 
characters immediately to the right of cursor. With a negative 
numeric argument of -n, it deletes the n characters immediately to 
the left of cursor. With any numeric argument, it saves the 
deleted characters on the kill history. 

Transposing Characters 

c-T Exchange Characters 

Transposes two characters (the ones on each side of the cursor). 

If the cursor is not at the end of a line, c-T transposes the 
character at the cursor and the character to the left of the cursor 
and advances the cursor one character. The result is that the 
character to the left of the cursor has been "dragged" one character 
position to the right. Repeated use of c-T continues to pull that 
character forward. This is useful when you are typing and enter 
two characters in the wrong order (for example, teh for the). 

If the cursor is at the end of a line, c-T transposes the two 
preceding characters. 

With a nonzero numeric argument of n, c-T deletes the character 
to the left of the cursor, moves forward n characters, and reinserts 
the deleted character. When n is negative, the cursor moves 
backwards. 
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c-T can only be given a numeric argument of zero when the mark 
is active. In this case, it exchanges the characters at point and 
mark. 
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Deleting and Transposing Words 



Introduction 

For a complete description of how words are delimited: See the 
section "Motion by Word", page 61. 

Deleting the 
Current Word 

m-D Kill Word 

Kills the word after the cursor and saves it on the kill history. If 
the cursor is in the middle of a word, n-D kills from the cursor to 
the end of that word. 

With a numeric argument n, it kills n words forward from the 
cursor. If n is negative, it kills backward. 

Deleting the 
Previous Word 

m-RUBOUT Backward Kill Word 

Kills the word before the cursor and saves it on the kill history. If 
the cursor is in the middle of a word, n-RUBOUT kills from the 
cursor to the beginning of that word. 

With a numeric argument n, it kills n words backward from the 
cursor. If n is negative, it kills forward. 

Transposing Words 

n-T Exchange Words 

Transposes the current word and the previous one. If the cursor is 
at the end of a line, n-T transposes the last word on that line and 
the first one on the next, regardless of the amount or type of white 
space between them. 

With a nonzero numeric argument n, n-T goes to the beginning of 
the current word, deletes the previous word, goes forward n words, 
and reinserts the deleted word. Moving forward a negative amount 
is equivalent to moving backward. An argument of zero transposes 
the words at point and mark. 
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Introduction 

Motion by Lisp expression repositions the cursor according to Lisp 
code delimiters: lists and expressions. A list is something enclosed 
in balanced parentheses. A Lisp expression is any readable printed 
representation of a Lisp object. 

Deleting the 

Current Lisp Expression 

c-n-K Kill Sexp 

Kills the Lisp expression immediately to the right of point and saves 
it on the kill history. 

With a numeric argument of n, it kills the n succeeding 
expressions. It is an error to kill off the end of a containing 
expression. When the numeric argument is negative, it kills 
backwards from point the same way. 

Deleting the 

Previous Lisp Expression 

c-n-RUBOUT Backward Kill Sexp 

Kills the Lisp expression immediately to the left of point and saves 
it on the kill history. 

With a numeric argument of n, it kills the n preceding expressions. 
It is an error to kill off the beginning of a containing expression. 
When the numeric argument is negative, it kills forward from point 
the same way. 

Deleting the List 
Containing the 
Current Lisp Expression 

Kill Backward Up List (c-n-X) 

Deletes the list that contains the Lisp expression after point, but 
leaves that expression itself. 

Transposing Lisp Expressions 

c-n-T Exchange Sexps 

Point must be between two expressions to use this command. 

Exchanges the two expressions on either side of point, preserving 
current indentation. 

With a numeric argument of n t it deletes the expression to the left 
of point, moves forward n expressions, and reinserts the deleted 
expression. With a negative numeric argument, it exchanges 
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expressions in the opposite direction. An argument of zero 
transposes the expressions at point and mark. 



March 1985 
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Deleting and Transposing Lines 



Introduction 



Down Line 



Lines are delimited by special characters called newlines. 



c-N 



Down Real Line 



Moves the cursor straight down to the corresponding column of the 
next line. If the cursor is positioned in the middle of the line, c-N 
moves it to the middle of the next one. 

With a numeric argument n> it moves the cursor down n lines. 
Moving down a negative number of lines is the same as moving up. 



Up Line 



c-P 



Up Real Line 



Moves the cursor straight up to the corresponding column of the 
previous line. If the cursor is positioned in the middle of the line, 
c-P moves it to the middle of the previous one. 

With a numeric argument of n, it moves the cursor up n lines. 
Moving up a negative number of lines is the same as moving down. 



Beginning of Line 
c-fl 



Beginning of Line 



Moves the cursor to the beginning of the current line. 

With a numeric argument of n> it moves the cursor to the 
beginning of the nth line after the current one, where the current 
line is numbered 1, the preceding line is numbered 0, and so on. 



End of Line 



c-E 



End Of Line 



Moves the cursor to the end of the current line. 



With a numeric argument of n y it moves the cursor to the end of 
the nth line after the current one, where the current line is 
numbered 1, the preceding line is numbered 0, and so on. 



Deleting the 
Current Line 



c-K 

Kills a line at a time and saves it on the kill history. 



Kill Line 



If the cursor is at the end of a line, c-K kills the newline, merging 
the current line with the next one. If the cursor is elsewhere on 
the line, c-K kills the text between the cursor and the end of the 
current line. 
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With a numeric argument n, c-K kills up to the nth newline 
following the cursor. When n is negative or zero, c-K kills back to 
the 1-nth newline before the cursor, c-9 c-K kills from the cursor 
back to the beginning of the line that it is on. 

Deleting 

Backward on the Line 

CLEAR INPUT Clear 

Kills backward to the start of the current line and saves it on the 
kill history. If point is already at the beginning of the line, it kills 
the previous line. With a numeric argument n, it kills between 
point and the start of the nth line above the current line. Use 
CLEAR INPUT when entering a new line of text, to delete the whole 
line. 



Transposing Lines 
of Text 



c-X c-T Exchange Lines 

Exchanges the current line with the previous one and leaves the 
cursor at the beginning of the next line. 

With a nonzero numeric argument n, c-x c-T deletes the previous 
line (including the following newline), moves down n lines, and 
reinserts the deleted line. 

With a numeric argument of zero, c-x c-T exchanges the lines at 
point and mark, advancing both point and mark to the beginning of 
the next line. 



83 
March 1985 Zmacs Manual 



Deleting Sentences 



Introduction 

According to Zmacs, sentences can end with question marks, 
periods, and exclamation points. Furthermore, these punctuation 
marks only end a sentence when followed by: 

• A newline 

• A space followed by either a newline or another space. 

However, Zmacs allows any number of closing characters, which are 
", ', ), and ], between the sentence-ending punctuation and the 
white space that follows it. A sentence also starts after a blank 
line. 

This corresponds closely to standard typing conventions. Zmacs 
does not recognize a period followed by one space as the end of a 
sentence, for example, as in "e.g. " or "Dr. ". 

Deleting the 
Current Sentence 

n-K Kill Sentence 

Kills the text between the cursor and the end of the current 
sentence, and saves it on the kill history. 

With a numeric argument of n, n-K kills the text between the 
cursor and the end of the nth sentence after the cursor, counting 
the current sentence. If the argument is negative, n-K kills -n 
sentences before the cursor, counting the current sentence. 

Deleting the 
Previous Sentence 

c-X RUBOUT Backward Kill Sentence 

Kills backward one sentence and saves it on the kill history. 

With a negative argument, c-X RUBOUT kills forward one sentence in 
a similar manner. 
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6. Working with Regions in Zmacs 



86 

Text Editing and Processing March 1985 



What is a Zmacs Region? 



Introduction to Regions 

Many Zmacs commands deal with the region. A region consists of 
a block of information within the buffer that you want to 
manipulate as a single entity. You define the area of the region, 
which can be any size, from characters or chunks of code to pages 
or the entire buffer. 

Zmacs keeps track of one or more locations in a buffer using buffer 
pointers. This section describes: 

• The two buffer pointers named point and mark 

• How Zmacs uses them to define the boundaries of a region 

• The point-pdl, a ring of pointers to saved locations 

• Registers, pointers to locations that you name and save 

• The region-manipulating commands 

Point and the Region 

Point (shown by the cursor) is the most important buffer pointer. 
Most editor commands depend on the position of point. Many 
editor commands, invoked by either the mouse or the keyboard, can 
be used to position point to the desired location in the buffer. 
Point points to one end of the region. 

Mark and the Region 

Mark points to the other end of the region. To mark a piece of 
text means to position point and mark on either side of the text, 
making it the region. The simplest way to mark some text is to 
position point (using either the mouse or keystrokes) to one 
boundary (either the beginning or the end) of the text, set the 
mark there (using the Set Pop Mark command), and then 
reposition point at the other boundary. See the section 
"Setting/Popping the Mark", page 88. 

Unlike point, the mark can be active or inactive. When mark is 
active, the region is shown on the screen by underlining. When 
mark is inactive, you cannot see it on the screen unless you 
reactivate it with c-X c-x. Although normally you cannot see an 
inactive mark, Zmacs keeps track of mark when it is inactive and 
sometimes uses mark in its inactive state. For example, c-Y leaves 
point and mark surrounding what it yanks, but does not activate 
mark, c-u immediately following c-Y kills the region even though it 
is not active, c-x c-x after c-Y activates mark, making the region 
visible. However, most commands will not use mark or the region 
unless it is active. You can set the mark three ways: when you 
create a region using the mouse, explicitly with the command Set 
Pop Mark (c-SPflCE), or with one of the commands to mark regions. 
See the section "Overview of Commands to Mark Regions", page 91. 
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When you set the mark, you activate it and make the region 
appear. 

Creating a Region 

You can create a region using either the mouse or keystrokes. 

Creating a Region 

with the Mouse 

The most common way to create a region is with the mouse. Hold 
down the left mouse button and drag the cursor. Let up the 
button to mark the end of the region. 

Holding down the middle mouse button creates a region, too. It 
marks the "thing" you point the mouse at, "thing" being mode- 
dependent (a word or Lisp expression if you point with the mouse 
at text, or a line if you point with the mouse at white space before 
or after all the text on the line). 



Creating a Region 
with Keystrokes 



You can also create a region using keystrokes. After setting the 
mark, you can move point either forward or backward to define a 
region in either direction; as you do so, Zmacs highlights the region 
with underlining. 

Typing a self-inserting character or c-G deactivates the mark and 
removes the underlining that highlights the region. The mark does 
not have an associated cursor like point. When inactive, the mark 
is invisible, but you can go to it with c-x c-x, Swap Point And 
Mark. 



The Point-pdl 



Zmacs maintains a special stack of buffer pointers called the 
point-pdl, where pdl stands for push-down list, another name for a 
stack. 

Zmacs automatically saves point on the point-pdl as it executes 
some commands (for example, n-<) that move point great distances. 
Whenever Zmacs pushes point onto the point-pdl, it displays "Point 
pushed" in the echo area, moves point to its new location, and 
pushes the previous point down onto the point-pdl. 

By popping the point-pdl, that is, resetting point to its last location 
as recorded on the point-pdl, Zmacs returns point to where it was 
when the pdl was last pushed. 
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Setting/Popping 
the Mark 

c-SPfiCE Set Pop Mark 

With no argument, c-SPRCE does three things: 

1. Puts mark where point is 

2. Makes mark active 

3. Pushes point onto the point-pdl 

Other commands can do each of these operations separately. 
Creating a region with the mouse sets a mark and makes it active 
but does not push point. 

This command does other things depending on how many c-Us are 
typed in front of it: 

Argument Action Taken 

one c-U Pops the location on the top of the point-pdl into 

point (typically puts point where it set the last 
mark). 

two c-us Pops the location on the top of the point-pdl and 

throws it away. 



Moving to 
Previous Points 

c-n-SPflCE Move to Previous Point 

Exchanges point and top of point-pdl. With a numeric argument n, 
it rotates a ring consisting of point and the top n-1 elements of 
point-pdl; thus the default argument is 2. With a numeric 
argument of 1, it rotates the entire point-pdl. A negative numeric 
argument rotates the ring in the other direction. 

c-x c-n-SPflCE Move to Default Previous Point 

Rotates the point-pdl, the same as c-n-SPRCE except that 
c-X c-n-SPfiCE has a default of 3. A numeric argument specifies 
the number of entries to rotate and sets the new default before 
rotating the point-pdl. 

Showing the Mark 

c-X c-X Swap Point And Mark 

Exchanges point and mark. It works even when no region is 
active. It highlights the text between point and mark. 
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Saving and 

Moving to 

Locations in Registers 

You can assign one-character "names" to locations in the buffer, 
which can be helpful for setting up a series of places in your text to 
which you want to return for some reason — to double-check 
several items without interrupting your text entry or editing, if you 
are considering a format change that will affect several parallel 
points, or simply to return quickly and easily to rough spots that 
require further work. 

c-X s Save Position 

Saves the current location in a register. It prompts for a one- 
character register name. 

c-X J Jump to Saved Position 

Moves point to a position that was saved in a register. It prompts 
for a register name and switches buffers to move to the saved 
position, if necessary. 

Saving and 
Inserting Regions 
in Registers 

c-X X Put Register 

Copies the text of the region into a register. It prompts for a 
register name. With a numeric argument, it deletes the region 
from the buffer after copying it. 

c-X G Open Get Register 

Inserts text from a specified register into the buffer. It prompts for 
the name of the register. It overwrites blank lines in the buffer 
the way RETURN does (using the command Insert Crs). It leaves the 
mark before the inserted text and point after it. With a numeric 
argument, it puts point before the text and the mark after. 

List Registers (m-x) 

Displays names and contents of all defined registers. It shows the 
name of the register and whether it contains a position or text. If 
the register contains a position, it tells which character on the line 
the position is at, and shows the first 50 characters on that line. 
If the register contains text, it shows the first 50 characters on the 
first line of that text. 
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List of all registers: 

D (text) This text was marked as a region and saved here 

1 (position) Char 0. in "another line containing a position" 

Done. 



View Register (ro-x) 

Displays the contents of a register in the typeout window. It 
prompts for a register name and then tells whether the register 
contains a position or text: 

Register A contains a position: Character in this line: 

this is the line 

or 

Register A contains text: 



Kill Register (n-x) 
Kills a register. 
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Commands to Mark Regions 



Overview 



To mark a piece of text means activating mark and then 
positioning point and mark on either side of the text, making it the 
region. The simplest way to mark some text is to go to one end of 
the text, set the mark there (using the Set Pop Mark command), 
and go to the other end of the text. See the section 
"Setting/Popping the Mark", page 88. However, several convenient 
commands mark different specific amounts of text: 

n-@ Marks a word. 

c-n-0 Marks an expression. 

c-n-H Marks a definition. 

n-H Marks a paragraph. 

c-X c-P Marks a page. 

c-x H Marks the whole buffer. 

c-> Marks to the end of the buffer. 

c-< Marks to the beginning of the buffer. 



Marking Words 



n-@ 



Mark Word 



Puts the mark at the end of the current word. With a numeric 
argument of n, n-Q puts the mark n words forward from point. 



Marking Lisp Expressions 



Mark Sexp 

Marks the current expression by putting mark at the end. 

With a numeric argument n, it moves forward n expressions and 
puts the mark there. For a more detailed description of how to 
move forward n expressions: See the section "Motion by Lisp 
Expression", page 65. 



c-m-H 



Mark Definition 



Puts point and mark around the current definition. 
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Marking Paragraphs 

n-H Mark Paragraph 

Puts the mark at the end of the current paragraph and moves 
point to the beginning, so that the current paragraph becomes the 
region. With a numeric argument n, n-H puts point at the 
beginning of the current paragraph and marks n paragraphs 
forward from there. 



Example 

n-3H marks the current paragraph and the following two; n — 1H 
marks the preceding paragraph. When marking preceding 
paragraphs, point is left at the end of the region, and when 
marking current and succeeding paragraphs, point is left at the 
beginning of the region. 

Marking Pages 

c-x c-P Mark Page 

Puts the mark at the end of the current page and moves point to 
the beginning, so that the current page becomes the region. 

With a numeric argument of n, c-X c-P marks the nth page after 
the current one. If n is zero, this is the current page; if n is 
negative, this page comes before the current page. 

Marking Buffers 

c-X H Mark Whole 

Marks the whole buffer by putting point at the beginning and the 
mark at the end. 

With any numeric argument, c-X H puts the mark at the beginning 
and point at the end. 
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Marking to End of Buffer 

c-> Mark End 

Marks from the cursor to the end of the buffer by putting the 
mark at the end of the buffer. 

Marking to 
Beginning of Buffer 

c-< Mark Beginning 

Marks from the cursor to the beginning of the buffer by putting 
the mark at the beginning of the buffer. 
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Region-manipulating Commands 



Saving a Region 

n-u Save Region 

Puts region on kill history list without deleting it. For information 
on kill merging and the Append Next Kill command, c-n-U: See 
the section "Kill Merging", page 75. 

Deleting a Region 

c-U Kill Region 

Deletes the region. If there is no region, c-U produces an error. 

This command ignores numeric arguments and places the deleted 
text on the kill history list. For information on retrieving history 
elements and the Yank command, c-Y: See the section "Retrieving 
History Elements", page 74. 

Compiling a Region 

c-sh-C Compile Region 

Compile Region (n-x) 

Compiles the region, or if no region is defined, the current 
definition. 

Transposing Regions 

c-X T Exchange Regions 

Exchanges two regions delimited by point and last three marks. 

After transposing regions, you can undo the effect of this command 
by invoking it again. 

Hardcopying a Region 

Hardcopy Region (n-x) 

Sends a region's contents to the local hardcopy device for printing. 

Filling a Region 

When Zmacs fills text it breaks it up so that it does not extend 
past the fill column. The fill column determines the right margin, 
and is the first column in which text is not to be placed by n-Q, 
n-G, or Auto Fill Mode formatting. In addition, the fill prefix, if 
set, is inserted: 

• At the beginning of each new line typed in while in Auto Fill 
Mode 

• At the beginning of each line in a paragraph for n-Q and each 
line in a region for n-G 
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The fill prefix determines the left margin, and is empty unless set 
to contain some combination of spaces and characters. If you do 
not set the fill prefix, the left margin is the left edge of your Zmacs 
window. For example, to insert five spaces at the beginning of 
every line, insert them at the beginning of the current line, and 
with point at column six, use c-x . . To turn this fill prefix off, 
put point at the beginning of a line, and use c-X . again. 

Adjusting or justifying text inserts extra spaces between the words 
to make the right margin come out exactly even. 

n-Q Fill Paragraph 

Fills the current (or next) paragraph. A positive argument means 
to adjust rather than fill. 

n-G Fill Region 

Fills the current region. A positive argument means to adjust 
rather than fill. 

c-X . Set Fill Prefix 

Defines Fill Prefix from the current line. All of the current line up 
to point becomes the Fill Prefix. Fill Region starts each nonblank 
line with the prefix (which is ignored for filling purposes). To stop 
using a Fill Prefix, do a Set Fill Prefix at the beginning of a line. 

Other Region- 
related Commands 

For descriptions of the following commands: 

Name and Invocation 

Uppercase Region c-x c-U 

Lowercase Region c-x c-L 

Uppercase Code in Region (n-x) 

Lowercase Code in Region (n-X) 

See the section "Changing Case of Regions in Zmacs", page 160. 
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Searching in Zmacs 



Overview 

Like other editors, Zmacs has commands for searching for an 
occurrence of a string. Zmacs search commands are incremental; 
that is, they begin to search as soon as you type the first character. 

This section describes how to search incrementally forward and 
backward in the buffer, as well as a method for specifying a 
complete search string first and then specifying a direction in which 
to search. 

Incremental Search 

The command to search is c-s (Incremental Search), c-s reads in 
characters and positions the cursor at the first occurrence of the 
characters that you have typed. If you type c-s and then t, the 
cursor moves right after the first t. Type an r, and see the cursor 
move to after the first tr. Add a y and the cursor moves to the 
first try after the place where you started the search. At the same 
time, the try has echoed at the bottom of the screen. Stop typing 
when you have typed enough characters to identify the place you 
want. 

You can rub out any character you type. After the try, pressing 
RUBOUT makes the y disappear from the bottom of the screen, 
leaving only tr. The cursor moves back to the tr. Rubbing out 
the r and t moves the cursor back to where you started the search. 
To exit from the search, press END or ESCAPE. You can also use 
ABORT to exit from the search. To abort out of the search and 
return to the original starting point in the buffer, use c-G. 

If you want to search for something else, press clear input to 
erase the current search string. You are still in the search loop, so 
type another search string. 

If the string cannot be found with c-S, type c-R to search 
backward for the default string. Zmacs remembers the default 
search string — you can reinvoke the search at any time using 
c-S c-S, to search forward for it, or c-R c-R to search backward. 

c-s Incremental Search 

Searches for a character string while you type it, searching forward 
to the end of the buffer. It prompts for a string in the echo area 
with I -Search:. As you type characters in, c-S displays the 
accumulating string in the echo area and searches for it at the 
same time. If no string is found, it displays Failing I-Search:. 
When it locates the string, it puts the cursor after it so that 
repeated c-ss locate subsequent occurrences of the default string in 
the buffer. 
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RUBOUT 
ESCAPE 

END or ESCAPE 
c-G 

c-Q 

c-S 
c-R 



Removes a character and backs up the search to 
the last' match. 

When typed before any search characters, 
switches to String Search. See the section "Zmacs 
String Search", page 100. 

Exits the search. 

Exits the search and returns to original starting 
point in the buffer. 

Quotes the next character, to prevent it from 
terminating the search. 

Repeats the search. 

Reverses the search to search backwards. 



If c-S or c-R is the first character typed, the previous search string 
is used again as the default. Entering any other command 
character terminates the search (and then executes that command). 

Reverse 
Incremental Search 

c-R, Reverse Incremental Search, works exactly the same way as 
c-S, except that it searches backward towards the top of the buffer 
from point, instead of forward. 



c-R 



Reverse Incremental Search 



Searches for a character string while you type it, searching 
backward to the beginning of the buffer. It prompts for a string in 
the echo area with Reverse I-Search:. As you type characters in, 
c-R displays the accumulating string in the echo area and searches 
for it at the same time. If no string is found, it displays Failing 
Reverse I-Search:. When it locates the string, it puts the cursor in 
front of it so that repeated c-Rs locate previous occurrences of the 
default string in the buffer. 



RUBOUT 



ESCAPE 



END or ESCAPE 
c-G 



Removes a character and backs up the search to 
the last match. 

When typed before any search characters, 
switches to Reverse String Search. See the 
section "Zmacs String Search", page 100. 

Exits the search. 

Exits the search and returns to original starting 
point in the buffer. 
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c-Q Quotes the next character, to prevent it from 

terminating the search. 

c-S Reverses the search to search forward. 

c-R Repeats the search. 

If c-S or c-R is the first character typed, the previous search string 
is used again as the default. Entering any other command 
character terminates the search (and then executes that command). 



String Search 



The string search command, invoked by c-S ESCAPE, lets you type 
in the entire string and specify the direction in which to search 
before starting the search. 

c-S ESCAPE String Search 

Searches for a specified string, according to the arguments given 
with the special characters below. Another c-S always begins the 
search. It prompts in the echo area String Search:. It saves 
previous string search commands on a ring, retrievable with c-D. 
The ring contains three elements and can be rotated with repeated 
c-Ds. While you are entering the search string, the following 
characters have special meanings: 

c-B Searches forward from the beginning of the 

buffer. 

c-E Searches backwards from the end of the 

buffer. 

c-F Leaves point at the top of the window, if the 

window must be recentered. 

c-G Aborts the search. 

c-D Gets a string to search for from the ring of 

previous search strings. 

c-L Redisplays the typein line. 

c-Q Quotes the next character. 

c-R Reverses the direction of the search. 

c-S Does the search, then comes back to the 

search command loop. 

c-U or CLEAR INPUT Erases all characters typed so far. 

c-y Delimited Search: Searches for occurrences of 

the string surrounded by delimiters. 
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c-U 



c-Y 

RUBOUT 

END or ESCAPE 



Word Search: Searches for words in this 
sequence regardless of intervening 
punctuation, white space, newlines, and other 
delimiters. 

Appends the string on top of the string ring 
to the search string. 

Rubs out the previous character typed. 

Does the search and exits. 



If you search for an empty string, it uses the default. Otherwise, 
the string you type becomes the default, and the default is saved 
unless it is a single character. 
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Overview of 

Locating and 

Replacing Strings Automatically 

c-Z, Replace String, searches forward for a string and replaces that 
string with another, c-7. prompts for the string to be replaced, 
reads the string from the minibuffer, and then reads the 
replacement string. After it goes through the buffer trying to 
make the replacements, it tells you how many replacements it made 
(1. replacement.), or that it made none. 

You can also substitute one string for another selectively 
throughout the buffer, with n-z, Query Replace. n-7. prompts first 
for the string to be replaced (Query-replace some occurrences of:), 
and then for the string to replace it with 

(Query-replace some occurrences of "string" with:). Terminate 
each string you specify with return, n-7. locates each occurrence 
and lets you decide what to do about each one. 

Making Global 
Replacements in Zmacs 

c-7. Replace String 

Replace String (n-x) 

Replaces all occurrences of a given string with another, where the 
string can be characters, words, or phrases. It prompts first for the 
string to remove and second for the string to replace it with. A 
numeric argument n means to make n replacements. By default, it 
begins at point and replaces all occurrences of the first string that 
occur after point in the buffer. Usually it attempts to match the 
case of the replacements with the case of the string being replaced. 
This behavior is controlled by the Zmacs variable Case Replace P 
(default t). When it is null, case matching does not take place. 
(For descriptions of Zmacs variables: See the section "How to 
Specify Zmacs Variable Settings", page 210.) 

Querying While 
Making Global 
Replacements in Zmacs 

n-7. Query Replace 

Query Replace (n-X) 

Starting at point, replaces a string through the rest of the buffer, 
asking about each occurrence, where the string can be characters, 
words, or phrases. It prompts for each string. You first give it 
stringi, then STRING2, and it finds the first stringi, displaying it in 
context. You respond with one of the following characters: 
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SPACE Replaces it with STRING2 and shows next STRING1. 

RUBOUT Leaves this STRING1, but shows next STRING1. 

Replaces this STRING1 and shows result, waiting 
for a sprce, c-R, or escrpe. 

Period Replaces this STRING1 and ends query replace. 

c-G Leaves this occurrence of STRING1 unchanged and 

terminates the query replace. 

ESCAPE Same as c-G. 

Returns to site of previous STRING1. 

c-U Kills this STRING1 and enters recursive edit. 

c-R Enters editing mode recursively. Press END to 

return to Query Replace. 

c-L Redisplays screen. 



Replaces all remaining STRING! s without asking. 



Entering any other character terminates the command. Usually 
the command attempts to match the case of the replacements with 
the case of the string being replaced. This behavior is controlled by 
the Zmacs variable Case Replace P (default t). When it is null, 
case matching does not take place. (For descriptions of Zmacs 
variables: See the section "How to Specify Zmacs Variable 
Settings", page 210.) 

If you give a numeric argument, it does not consider STRING1S that 
are not bounded on both sides by delimiter characters. 

Querying While 
Making Multiple 
Global Replacements 

While doing multiple query replacements, you can specify the 
replacement strings either from the minibuffer or from another 
buffer altogether. 

Multiple Query Replace (n-X) 

Performs query replace using many pairs of strings at the same 
time, where the strings can be characters, words, or phrases. (See 
the section "Querying While Making Global Replacements in 
Zmacs", page 102.) Strings are read in alternate minibuffers; when 
you finish entering all strings, press RETURN twice. An argument 
means that the strings must be surrounded by delimiter characters. 
A negative argument means that the strings must be delimited Lisp 
objects (not lists), rather than words. 
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Multiple Query Replace From Buffer (n-X) 

Performs query replace using many pairs of strings supplied from 
the specified buffer. (See the section "Querying While Making 
Global Replacements in Zmacs", page 102.) The current buffer 
should contain a STRING"! , a space, and a STRING2. Put quotation 
marks around any string that contains a space, tab, backspace, 
semicolon, or newline character. Lines in the buffer that begin 
with a semicolon or are blank are ignored. In other words, each 
string in the buffer is a Lisp string, but quotation marks can be 
omitted if the string contains no special characters. 

Other Types of 
Replacement 
Operations in Zmacs 

Besides making string replacements in text, Zmacs commands 
replace: 

• A region into the kill history 

• Evaluated code into the buffer 

• The value of LET into its variable 

• A string for delimited Lisp objects (not lists or nil) 

Query Replace Last Kill 

Query Replace Last Kill (n-X) 

Replaces the first item in the kill history with the region. 

Evaluate and 
Replace Into Buffer 

Evaluate And Replace Into Buffer (n-X) 

Evaluates the Lisp object following point in the buffer and replaces 
it with its result. 
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Query Replace Let Binding 

Query Replace Let Binding (n-x) 

Replaces variable of LET with its value. Point must be after or 
within the binding to be modified. 

Atom Query Replace 

Atom Query Replace (n-x) 

Performs query replace for delimited Lisp objects (except for lists or 
nil). (See the section "Querying While Making Global 
Replacements in Zmacs", page 102.) 
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Introduction 

Tag tables, a means of global searching and replacing, allow you to 
make sweeping changes to groups of files without having to 
explicitly locate each file. A tag table is a Zmacs support buffer, (a 
temporary buffer), that contains the names of sets of buffers and 
files, which you specify. You can edit these specified buffers and 
files as a unit, once you have specified them as items in a tag table. 
Tag tables remain active for the duration of the Zmacs session; you 
cannot permanently save tag tables. 

You could use tag tables, for example, to: 

• Search for all references to a certain variable and alter them 
consistently 

• Search for all occurrences of an obsolete term and update it 

• Search for all functions that send a certain message 

How Tag Tables Work 

First, you specify the buffers or files that will make up the tag 
table. See the section "Specifying and Listing Tag Tables", page 
106. Then you can perform an operation. See the section 
"Performing Operations with Tag Tables", page 107. Zmacs 
performs the operation on the files within the tag table that you 
have specified. 



Example 

Suppose you want to perform a tag query replace in several files. 
Use Tags Query Replace (n-x) to begin: See the section 
"Performing Operations with Tag Tables", page 107. The minibuffer 
prompts as in Query Replace (n-x) for the string to be replaced and 
the replacement string. The operation begins and Zmacs displays 
Control-, is now Continue query replacement of "string-old" with 
"string -new"; as it displays each occurrence, you deal with each one 
using the appropriate response characters. Tags Query Replace 
goes through all the files specified in the tag table, listing their 
names in the minibuffer and stopping at each occurrence of "string- 
old". When it finishes searching all the files, it displays No more 
files. 

Specifying and 
Listing Tag Tables 

Select All Buffers As Tag Table (n-X) 

Selects all buffers currently read in. It creates a support buffer 
called *Tag-Table-iV*, which contains a list of the names of all the 
buffers. See the section "Support Buffers", page 109. 
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Select Some Buffers As Tag Table (n-x) 

Selects some buffers currently read in, querying about each one. 
With a numeric argument, it asks only about buffers whose name 
contains a given string. 

Select Tag Table (n-x) 

Makes a tag table current for commands like tag search. It 
prompts in the minibuffer for the name of the tag table to use. 

Select System As Tag Table (m-X) 

Creates a tag table for all files in a system defined by defsystem. 
It prompts in the minibuffer for the name of a system — press 
HELP to see a display of system names. It selects the system but 
does not read the files in. 

List Tag Tables (n-X) 

Lists in the typeout window the names of all the tag tables, and 
for each one shows the files it contains. 



Performing 
Operations with 
Tag Tables 

Tags Search (n-X) 



Searches for the specified string within files of the tag table. It 
prompts in the minibuffer for the search string. If there is no 
current tag table, it prompts for one. 

Zmacs displays in the echo area the name of each of the files in 
the tag table as it searches each file for the specified string. As 
Zmacs begins the operation and finds the first occurrence, it 
displays Point pushed, in the minibuffer and moves the cursor to 
the occurrence. After you deal with that occurrence, use c-. , the 
Next Possibility command, to tell locate the next occurrence. (See 
the section "Displaying the Next Possibility", page 110.) Go through 
the specified files using c-. to the end. 

Tags Query Replace (m-x) 

Replaces occurrences of one string with another within the files of 
the tag table, asking about each occurrence. It prompts first for 
the string to remove and second for the string to replace it with. 
You first give it STRING1, then STRING2, and it finds the first 
STRING1, displaying it in context. You respond with one of the 
following characters: 
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sprce Replaces it with STRING2 and shows next stringi. 

RUBOUT Does not replace this occurrence, but shows next 

STRINGI. 

, Replaces this STRINGI and shows result, waiting 

for a space, c-R, or escape. 

Period Replaces this STRING1 and terminates the query 

replace. 

c-G Leaves this occurrence of STRING1 unchanged and 

terminates the query replace. 

escape Same as c-G. 

Returns to site of previous STRING1 (actually, pops 
the point-pdl). 

c-u Kills this STRINGI and enters recursive edit. 

c-R Enters editing mode recursively. Press END to 

return to Query Replace. 

c-L Redisplays screen. 

! Replaces all remaining STRING! s without asking. 



Entering any other command character terminates the command. 
Usually the command attempts to match the case of the 
replacements with the case of the string being replaced. This 
behavior is controlled by the Zmacs variable Case Replace P (default 
t). When it is null, case matching does not take place. (For 
descriptions of Zmacs variables: See the section "How to Specify 
Zmacs Variable Settings", page 210.) 

If you give a numeric argument, it does not consider STRING1S that 
are not bounded on both sides by delimiter characters. 

Tags Multiple Query Replace (n-X) 

Performs tags query replace using many pairs of strings at the 
same time, where the strings can be characters, words, or phrases. 
Strings are read in alternate minibuffers; when you finish entering 
all strings, press return twice. An argument means that the 
strings must be surrounded by delimiter characters. A negative 
argument means that the strings must be delimited Lisp objects 
(excluding lists and nil), rather than words. 

Tags Multiple Query Replace From Buffer (n-X) 

Replaces occurrences of any number of strings with other strings 
within the tag table files, asking about each change. The current 
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buffer should contain a stringi, a space, and a STRING2. Put 
quotation marks around any string that contains a space, tab, 
backspace, semicolon, or newline character. Lines in the buffer 
that begin with a semicolon or are blank are ignored. In other 
words, each string in the buffer is a Lisp string, but quotation 
marks can be omitted if the string contains no special characters. 

A positive numeric argument means to consider only the cases 
where the strings to replace occur as a word (rather than within a 
word). A negative numeric argument means to consider only 
delimited Lisp objects (excluding lists and nil), rather than words. 

This command has the same options as Tags Query Replace. 

Find Files in Tag Table (n-x) 

Reads every file in the selected tag table into the editor. If there is 
no current tag table, it prompts for the name of one, which you 
can specify as a file (F), all editor buffers (B), or a system (s). 

Visit Tag Table (n-x) 

Creates a tag table by reading in a tag file. First, it reads in the 
specified tag file. It prompts for a file name from the minibuffer. 
Next, it goes through the tag file and marks the name of each tag 
as being a possible section of its file. The Edit Definition command 
(n-. ) uses these marks to figure out which file to use. 

It uses a support buffer to hold the elements of the tag table and 
another support buffer to hold the state of a pending operation 
involving all the files in the tag table. See the section "Support 
Buffers", page 109. Each contains the names of the files. 

Support Buffers 

Zmacs creates support buffers to save lists that it creates as part of 
the execution of some commands: 

• Tag table commands. 

• Edit Buffers (n-x). 

• View File (n-x). 

• Lists for Edit Definition (n-.), when more than one definition 
exists. 

• Buffers for Dired (n-x). 

• Everything that edits a sequence of definitions, as in List Callers 
(n-x) or List Methods (n-x). 

This means that you can examine the buffers containing the lists 
even after you have done some editing. 

c-X c-B, the List Buffers command, displays these support buffers 
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in the listing of buffers. Their names are, for example, 
*Definitions-1«, *Tags-Search-1*, and *Tags-Query-Replace-1*. 

To avoid proliferation of editor buffers, Zmacs reuses support buffers 
in most cases, so that it usually saves no more than two of each 
type of support buffer at a time. 

Possibility Buffers 

Each time you use a command that generates a set of possibilities 
(for example, Tags Search (n-x) and Tags Query Replace (n-x)), it 
creates a possibility buffer for that set and pushes the set of 
possibilities onto a stack, c-., Next Possibility, extracts the next 
item from the set at the top of the stack. The set is popped from 
the stack when no more items remain in it. Several informational 
messages are associated with this facility. When the whole 
possibilities stack is empty and you have nothing more pending it 
displays: 

No more sets of possibilities. 

Displaying the Next Possibility 

c-. Next Possibility 

Selects the next possibility for the current set of possibilities. With 
a negative argument, pops off a set of possibilities. An argument of 
c-U or any positive number displays the remaining possibilities in 
the current set. With an argument of zero, selects the current 
buffer of possibilities. 

For a description of the Edit Definition and Edit Callers commands: 
See the section "Editing Lisp Programs in Zmacs", page 169. 



Example 



Suppose you had been using c-. to move through the set provided 
by Tags Search and you then used Tags Query Replace to push a 
new set of possibilities onto the stack. When you finished the set 
provided by Tags Query Replace, you would see a message like the 
following to notify you that the empty set had been popped off the 
stack and the set of possibilities for Tags Search had been 
reinstated.: 

c-. is now Search for next occurrence of "string" 

The position of point in the support buffer indicates the next item 
for Next Possibility (c-. ). You can select the support buffer and 
move point manually in order to skip or redo possibilities. 

Typing c-. while in a support buffer that is not at the top of the 
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possibilities stack moves it to the top, prints an appropriate 
message, then takes the .next possibility from that support buffer. 



112 

Text Editing and Processing March 1985 



Sorting 



Overview 



The Zmacs sorting commands alphabetically sort a region by line, 
paragraph, or whatever sort key you specify. 



Zmacs Sorting Commands 

Sort Lines (n-x) 



Sorts the region alphabetically by lines. 



Sort Paragraphs (m-x) 

Sorts the region alphabetically by paragraphs. 

Sort Via Keyboard Macros (n-x) 

Sorts the region, prompting for actions to define the records (the 
units of the region to be rearranged) and the sort keys (the fields 
in the records that are compared alphabetically to determine the 
new order of records). It prompts you to define the records and 
sort keys by performing positioning commands. It prompts for 
three actions: 

1. Move to the beginning of the sort key (that is, move the cursor 
to the beginning of the field upon which to sort). 

2. Move to the end of the sort key (that is, move to the end of the 
sort field). 

3. Move to the end of the sort record (that is, move to the end of 
the record containing that field). 

For each, it records the keystrokes that you use (as keyboard 
macros) and plays those back to find and sort the records in the 
region. 
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Overview 

Files are semipermanent collections of information stored safely 
outside the Zmacs environment. Buffers, on the other hand, are 
more dynamic, temporary collections of information, used by Zmacs 
for manipulating text. Buffers live in the active Zmacs 
environment. Each buffer has its own point and mark as well as 
other associated information. 

We say we use Zmacs to "edit files", but what we really do is copy 
a file into a buffer created for the purpose, edit the buffer, and 
then write out a new version of the file from the edited buffer. 
The old version of the file is retained, to be deleted explicitly when 
appropriate. Successive versions of files are distinguished by version 
number, a component of the file name that is incremented with 
each new revised copy (except on file server hosts such as UNIX 
that do not have version numbers). 

Zmacs allows multiple buffers, so that you can edit many files 
simultaneously. Usually only one buffer is visible on the screen at a 
time. You can, however, divide the screen into multiple windows so 
that you can view the contents of several buffers at once. 

Zmacs keeps track of the association between files and buffers. If 
you are editing a file's contents in a buffer, Zmacs gives that buffer 
the same name as that of the file being edited. 

Buffer and File Names 

Both buffers and files have long names that indicate the host 
directory as well as the file name (and version, where supported). 
Hence completion is a necessary aid and is always provided for 
entering buffer and file names. 

Buffer Flags for 
Existing Files 

Each buffer has a modification flag that tells whether the buffer 
has been changed to be different from the associated file. You can 
see the modification flag by clicking on either the List Buffers 
command or the Kill or Save Buffers command in the editor menu 
(editor menu is click right once), or by pressing c-x c-B for List 
Buffers. 

The modification flag is cleared when: 

• The file is read into the buffer from the file system. 

• The buffer is saved, that is, whenever its contents are written 
out to the associated file. As soon as its contents are modified 
thereafter, the modification flag is set and Zmacs displays an 
asterisk (*): (1) in the mode line to the right of the buffer 
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name, and (2) whenever it displays output from the List Buffers 
command. 

Buffer Flags for 

New Files 

The List Buffers (c-x c-B) command uses the plus sign (+) to mark 
new files that have not been saved. In addition, it uses + to mark 
new buffers, not associated with files, that have text in them. This 
helps when you put text into a new buffer and later want to be 
reminded to write that buffer to a file. 
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Current Buffer 

At all times when using Zmacs, you have one selected buffer, which 
is the buffer that you are actively editing. This is the buffer in 
which all current activity takes place until you switch buffers. 



Buffer History 



With a single Zmacs window on the screen, the editor keeps one 
buffer history, the global history list, which remembers the 
previous-buffer history (stack history) of that window. The top 
buffer in the stack is the currently selected one. Usually, when a 
buffer is selected, it is pulled out of the stack and put on top. The 
buffers near the top are usually the most recently used. Each time 
you change buffers Zmacs offers the name of the most recently 
used buffer as the default buffer name. 

When we refer to the nth buffer, we mean the nth buffer in 
Zmacs's stack of buffers. 

Every additional window maintains its own buffer history, but the 
global history list continues to display an entry for every buffer in 
every window. 

When you create a new window, Zmacs initially takes the history 
list for the new window from the global history list. From then on, 
as you switch from buffer to buffer within that window, the list for 
that window reflects the history of those changes in chronological 
order. This affects particularly c-m-L (Select Previous Buffer) and 
the default for c-x B (Select Buffer). 

The global history list still exists and is used for name completion 
and c-X c-B (List Buffers). 



117 
March 1985 Zmacs Manual 

Buffer Commands 



Changing Buffers 

c-X B Select Buffer 

Prompts for the name of a buffer and selects that buffer, displaying 
its contents on the screen. If you press END or RETURN instead of a 
name, it reselects the second most recently selected buffer. 

Using completion, it takes the string you enter and tries to 
complete it to an existing buffer name: 

• When completion is successful, it selects that buffer. 

• When completion is unsuccessful, (there is no buffer with the 
name given), it either waits for you to type more characters (if 
there are multiple possible completions) or it beeps to give you a 
chance to correct a typing error (if there is no possible 
completion). A subsequent response of c-RETURN creates a new 
buffer with the specified name and selects it. 

If you precede the c-X B command with a numeric argument, 
Zmacs prompts for the name of the buffer and then creates and 
selects it. 

c-n-L Select Previous Buffer 

Selects a previously selected buffer. With a numeric argument n> it 
selects the nth previous buffer. The default argument is 2. When 
the argument is 1, it rotates the entire buffer history. A negative 
argument means to rotate the other way. An argument of zero 
displays the buffer history, which is mouse sensitive. 

c-X c-n-L Select Default Previous Buffer 

With a numeric argument n, this is exactly the same as c-n-L. 
Without a numeric argument, this command remembers the last 
numeric argument it received and uses that as its argument this 
time. 

This is useful if you happen to be working with the top few buffers 
on the buffer stack and want to cycle among them without having 
to remember how many there are. 

Listing Buffers 

c-X c-B List Buffers 

Lists all the currently existing buffers in the typeout window, along 
with the editor mode of the buffer and the name of the associated 
file, if any. For buffers with associated files, it displays the version 
number of the file, if any. If there is no associated file, c-X c-B 
gives the size of the buffer in lines instead. For Dired buffers, it 
displays the pathname used for creating the buffer. It lists 
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modified buffers with an asterisk. It lists the buffers sorted in 
stack order. You can inhibit this sorting by setting the global 
variable zwei:*sort-zmacs-buffer-list* to nil (default is t). 

With an argument of c-u, it prompts for a substring and then lists 
all buffers whose names contain that substring. 

The buffer names are mouse sensitive. Click right on the name of 
the buffer for a menu of operations (Kill, Not Modified, Save, 
Select) for that buffer. You can select one of the buffers by 
clicking left on its name. 



Example 



Buffers in Zmacs: 
Buffer name: File Version: Major mode: 

+ f i lei /dess/zmacs VIXEN: (Fundamental) 

= *Dired-1* VIXEN: /dess/zmacs/* (Dired) 

* doc.mss /dess/zmacs VIXEN: (Text) 

*Buffer-l* [1 line] (Fundamental) 

+ means new file or non-empty non-file buffer. * means modified file. 
= means read-only. 



Editing Buffers 

Edit Buffers (c-m-X) is not part of the standard comtab. It is 
similar to List Buffers (c-X c-B), except that the buffer listing that 
Edit Buffers produces is a buffer in its own right. (For an example 
showing how to make c-X c-B call Edit Buffers instead of List 
Buffers: See the section "Setting Editor Variables in Init Files", 
page 213.) It contains one line for each of the buffers in the editor. 

Edit Buffers (c-n-X) 

Displays a list of all buffers, allowing you to save or delete buffers 
and to select a new buffer. A set of single character subcommands 
lets you specify various operations for the buffers. For example, you 
can mark buffers to be deleted, saved, or not modified. The buffer 
is read-only; like the Directory editor (Dired) buffer, you can move 
around in it by searching and with commands like c-N and c-P. 

The lines in the list are not mouse sensitive. With the cursor on 
the line for a buffer, the following single character commands apply 
to that buffer: 

RUBOUT Undeletes buffer above the cursor. 
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SPACE Selects the specified buffer immediately. 

D Marks the buffer for deletion (K, c-D, c-K are 

synonyms). 

u Undeletes either the buffer on the current line or 

the buffer on the line above. 

s Marks the buffer for saving. 

Marks the buffer for setting not modified. 

X Executes an extended command (same as n-x). 



Viewing a Buffer 

View Buffer is for when you want to just look at a buffer, not edit 
it. 

c-x y View Buffer 

View Buffer (n-x) 

Prompts for the name of a buffer and prints out the buffer 
contents for viewing only in the typeout window. If there is more 
than a screenful, it pauses between screenfuls, displaying a --more-- 
message at the bottom. 

space, c-y, scroll Displays the next screenful. 

BACKSPACE, n-V Displays the previous screenful. 

RUBOUT Exits. 

Anything else exits and is executed as a command. 

Hardcopying the Buffer 

Hardcopy Buffer (m-x) 

Prompts for the name of a buffer and then prints the specified 
buffer on the local hardcopy device. 

Renaming the Buffer 

Rename Buffer (n-X) 

Prompts for a new name for the current buffer and changes the 
name accordingly. This operation removes any file association that 
the buffer had. 
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Saving Buffers 

Save All Files (n-X) 

Offers to write out each buffer that is associated with a file. It 
prompts in the typeout window with the name of each buffer: Save 
file old. lisp /dass/pubs/pgs VIXEN:? (Y or N). 



Encrypting and 
Decrypting the Buffer 

Encrypt Buffer (n-X) 



Encrypts the contents of the buffer. It prompts for a key and does 
not echo it as you type it. It prompts for the same key again, just 
in case you mistyped it because of the lack of echoing, and makes 
sure you typed it the same both times. The encryption algorithm 
is the same one used by the Hermes mail-reading system. 

Decrypt Buffer (n-X) 

Decrypts the contents of an encrypted buffer. It prompts for a key 
and does not echo it as you type it. The encryption key given for 
decrypting must match the one used for encrypting. The 
encryption algorithm is the same one used by the Hermes mail- 
reading system. 

Reading a File 
Into a New Buffer 

Edit File (n-X) 

c-X c-F Find File 

Prompts for the name of a file and looks for a buffer currently 
associated with that file. If one is found, it selects it. Otherwise, 
it creates a new buffer and reads that file into it. 

When you read a file that has a Lisp file type into the buffer, if 
that file does not begin with an attribute line containing Base and 
Syntax attributes, Zmacs warns that the file "has neither a Base 
nor a Syntax attribute" and announces that it will use the defaults, 
Base 10 and Zetalisp. See the section "Buffer and File Attributes". 

Reading a File 

Into an Existing Buffer 

The c-X c-y command, Visit File, is primarily useful when you type 
in a mistaken file name after c-x c-F and Zmacs responds (New 
File). You can simultaneously read in the correct file and get rid 
of the unwanted buffer with Visit File. 
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c-X c-V Visit File 

Prompts for the name of a file and reads that file into the current 
buffer. This action associates the current buffer with the specified 
file. 

This command can only be used if the current buffer is not already 
associated with an existing file. 

Writing the 
Buffer Contents 
to a File 

c-X c-U Write File 

Prompts for the name of a file and writes out the contents of the 
current buffer to the specified file. This changes the current 
buffer's name and associates it with the specified file. Subsequent 
saves using c-X c-s save to the newly specified file. This operation 
clears the modification flag. 

Saving the Buffer 
Contents to the File 

c-X c-s Save File 

Writes the contents of the current buffer out to the associated file 
and clears the modification flag. It does not write the file if the 
buffer is unchanged from when the file was last visited or saved. 
It reads a file name from the minibuffer if the current buffer does 
not have an associated file. 

Re-reading a File 
Into the Buffer 

Revert Buffer (n-x) 

Re-reads information into the buffer that it is associated with. For 
example, you can revert a Dired buffer to see the most current 
listing of that directory. You can also read in the most up-to-date 
version of a file. The command prompts for a buffer name, 
defaulting to the current buffer. The prompt serves as a 
confirmation, since Revert Buffer (n-X) throws away any 
modifications made to the buffer since you last saved or read the 
file or other information. This command is useful if you have 
damaged the buffer and want to start over or if the associated file 
is more current than the buffer. This operation clears the 
modification flag. 

Refmd File (n-X) 
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Re-reads a specified file into its associated buffer only if that file 
has changed on disk. The command prompts for a buffer name, 
defaulting to the current buffer. If the associated file on disk has 
changed, it re-reads the file into the buffer. If the associated file 
on disk has not changed, it tells you that it is not necessary to 
refind that file. This command is useful when more than one 
person works on the same program. 

Refind All Files (n-x) 

Re-reads only those files that have changed on disk into their 
associated buffers, asking about each one. If the associated file on 
disk has not changed, the command tells you that it is not 
necessary to refind that file. This command is useful when more 
than one person works on the same program. 

With a numeric argument, Zmacs asks you for a string, which it 
matches with any part of the buffer names and operates only over 
buffers whose names contain that string. 

Creating a 
Fundamental 
Mode Buffer 

Find File In Fundamental Mode (n-x) 

Creates a fundamental mode buffer containing the file. This is 
useful because Zmacs does not parse the file while reading it in, 
thus the names of the functions in the file do not conflict with 
those already known to completion in n-. and similar commands. 
This command is necessary if the normal parsing of a Lisp Mode 
file signals an error, preventing it from being read into the editor to 
correct the cause of the error. 



Associating a File 
with a Buffer 

Set Visited File Name (m-x) 



Prompts for the name of a file and associates the current buffer 
with that file. This command does not read the specified file into 
the buffer. Effectively, the current contents of the buffer are 
declared to be the new intended contents of the specified file. This 
command should be used with caution to avoid unintentionally 
destroying the old contents of the specified file. 



123 
March 1985 Text Editing and Processing 

Buffer Commands, cont'd. 



Destroying Buffers 

c-X K Kill Buffer 

Prompts for the name of a buffer and destroys that buffer. If you 
press END or RETURN instead of a name, c-K destroys the current 
buffer and prompts for the name of a buffer to select instead. 

Kill Some Buffers (n-x) 

For each existing buffer, tells you something about the status of 
the buffer and asks whether or not to delete it. If you elect to 
delete a buffer that has been modified since it was last saved, the 
command offers to save it first. 

Kill Or Save Buffers (n-x) 

Puts up a multiple-choice menu listing all existing buffers. Choices 
are: Save, Kill, Unmodify, and Hardcopy. Specify these options next 
to the buffer names in the menu. This command appears on the 
editor menu. 
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Appending a 
Region to a Buffer 

c-x fl Append To Buffer 

Prompts for the name of a buffer and appends the contents of the 
region onto the end of the specified buffer. 

Appending a 
Region to a File 

Append To File (n-X) 

Prompts for the name of a file (Append region to end of file:) and 
appends the contents of the region onto the end of the specified 
file, writing a new version of that file. 

Prepending a 
Region to a File 

Prepend To File (n-X) 

Prompts for the name of a file and prepends the contents of the 
region onto the beginning of the specified file. 

Inserting a Buffer 
Into Another Buffer 

Insert Buffer (n-X) 

Prompts for the name of a buffer and inserts the entire contents of 
that buffer into the current buffer at the cursor. 

Inserting a File 
Into a Buffer 

Insert File (n-X) 

Prompts for the name of a file and inserts the contents of that file 
into the current buffer at the cursor. 
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Source Compare 

Source Compare (n-x) 



Example 



Compares two files or buffers, prompting for type (F or B) and 
name of each, and displays the results of the comparison in the 
typeout window. It saves the output in a support buffer named 
*Source-Compare-iV*. You can read the comparison while checking 
the file, for example, by going into two window mode with the 
comparison in one window and the file in the other. 



This example shows a comparison between the file new, as it was 
read into the buffer, and the buffer new, which contains the 
contents of the file new plus changes that have been made: 

Source compare made by ESG on 5/21/84 12:30:40 -^-Fundamental-*- 
of Buffer new /dass/pubs/pgs VIXEN: with File 
VIXEN: /dass/pubs/pgs/new 

****Buffer new /dass/pubs/pgs VIXEN:, Line #179 
Source Compare Merge compares two files or buffers, 
prompting for type and name, and merges the differences 

****File VIXEN: /dass/pubs/pgs/new, Line #179 
Compares two files or buffers, prompting for type and 
name, and merges the differences 

*************** 
Done. 



Source Compare Merge 

Source Compare Merge (n-x) 



Compares two files or buffers, prompting for type and name, and 
produces a new version that reconciles the differences between the 
two. You choose which version (if any) to accept. You can also 
manually edit one or both versions. 

At each place where the sources differ, the command prompts you 
twice. The first time you specify what to do to resolve the 
difference (prompts: Specify which version to keep:). (For 
example, you can keep one or the other version, both of them, or 
neither.) Respond to the prompt using these subcommands: 

Option Action 

1 Leaves the first alternative in the text, redisplays the 

contents, and asks for confirmation of change. 
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2 Leaves the second alternative in the text, redisplays 

the contents, and asks for confirmation of change. 

* Leaves both alternatives in the text, redisplays the 

contents, and asks for confirmation of change. 

I Leaves both alternatives in the text, along with the 

message lines from the source compare (*** MERGE 
LOSSAGE ***), but does not ask for confirmation. 

SPRCE Leaves both alternatives in the text, but does not 

redisplay the contents or ask for confirmation. 

! Disposes of this and all remaining differences the 

same way, without confirmation. It asks: What to do 
with remaining differences (1, 2, *, I, or 
RUBOUT?) It uses whichever option you choose for the 
rest of the differences. 

c-R Exits from the prompt and allows you to edit. Press 

END to return to this question. 

RUBOUT Leaves nothing in the new buffer and does not 

redisplay the contents or ask for confirmation. 

The second time you confirm or reject the change that was made. 
The screen now shows the change that was made as a result of 
your choice and prompts: Please confirm the change that has been 
made: (SPACE, RUBOUT, or c-R). Confirming it keeps that change 
and moves on to the next difference. Rejecting it returns to the 
prior appearance so that you can make a different choice: 

Option Action 

SPACE Yes, that's right. 

RUBOUT No, take that back. 

c-R Exits from the prompt and allows you to edit. Press 

END to return to this question. 

When you finish confirming your decisions, Zmacs incorporates all 
changes into the new version in the specified buffer and the 
minibuffer displays: Done. Resectionizing the buffer. 

Source Compare Merge also has a mouse interface. You can answer 
the first question by clicking left on the text you want to keep or 
on the dividing line between them to keep both. You can answer 
the second question by clicking left for "yes" (changes confirmed) or 
middle for "no" (changes rejected). 
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Compare/Merge 
Commands for Definitions 

The compare/merge commands operate on definitions by comparing, 
or comparing and merging, the current version with the newest 
version, newest version on disk, or installed version. 

Comparing/Merging 
Current/Newest Versions 

Source Compare Newest Definition (n-X) 

Compares the current definition with the newest version in the 
normal source file for this definition, regardless of patch files. This 
command never looks in patch files; it only looks in original source 
files. If the definition was added by a patch (so that no original 
source file was recorded), the command cannot find the name of 
the source file. However, if you read the source file into the editor, 
it finds the definition in the editor buffer. You can use this 
command for comparing patch files and source files. 

Source Compare Merge Newest Definition (n-X) 

Compares and merges the current definition with the newest 
version in the normal source file. This command never looks in 
patch files; it only looks in original source files. If the definition 
was added by a patch (so that no original source file was recorded), 
the command cannot find the name of the source file. However, if 
you read the source file into the editor, it finds the definition in the 
editor buffer. You can use this command for comparing patch files 
and source files. 

Comparing/Merging 
Current/ Saved Versions 

Source Compare Saved Definition (n-X) 

Compares the current definition with the source for the newest 
version on disk. 

Source Compare Merge Saved Definition (n-X) 

Compares and merges the current definition with the source for the 
newest version on disk. 

Comparing/Merging 
Current/Installed Versions 

Source Compare Installed Definition (n-X) 

Compares the current definition with the source for the installed 
version. 
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Source Compare Merge Installed Definition (n-X) 

Compares the current definition with the source for the installed 
version, merging the results. 
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Using Two 

Windows, Select Bottom 

c-X 2 Two Windows 

Shows two windows, selecting the bottom one. It splits the frame 
into two editor windows, selects the bottom one, and displays the 
next buffer from the global history in it. With a numeric 
argument, it displays that same buffer in the second window. 

Using Two 
Windows, Select Top 

c-X 3 View Two Windows 

Shows two windows, selecting the top one. It splits the frame into 
two editor windows, selects the top one, and displays the next 
buffer from the global history in it. With a numeric argument, it 
displays that same buffer in the second window. 

Creating Two 

Windows, 

Specifying Other Contents 

c-X 4 Modified Two Windows 

Selects a buffer, file, or definition in the other window. c-X 4 
combines the functions of splitting the frame and selecting contents 
for the second window. It prompts for the type of contents you 
want for the second window: Select what in other window? (B, F, 
D, or J), for buffer, file, definition, or jump to register. Then it 
reads the name of the file, buffer, definition, or register that you 
want to select for that window. 

Creating Two 
Windows with the 
Region in Top 

c-X 8 Two Windows Showing Region 

Makes two windows on the same buffer, with the top one 
displaying the current region. 

Changing Window Size 

c-X * Grow Window 

Changes the size of the current window by some number of lines. 
With a positive numeric argument, it expands the window; with a 
negative numeric argument, it shrinks the window. 
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Choosing the 
Other Window 

c-X Other Window 

Moves the cursor to the other window. 

Returning to One Window 

c-X l One Window 

Returns the editor frame to displaying only one window. It 
expands the current window to use the whole frame. With a 
numeric argument, it expands the other window to use the whole 
frame. 



Scrolling the 
Other Window 



c-n-V Scroll Other Window 

Scrolls the other window up several lines. By default, it scrolls the 
same way as c-v. With no argument, it scrolls a full screen. With 
just a minus sign as an argument (c-m- -V), it scrolls a full screen 
backward. A numeric argument tells it how many lines to scroll — 
a positive number scrolls forward, a negative number scrolls 
backward. 



Splitting the Screen 

Split Screen (m-X) 



Pops up a menu that offers to create a new buffer or find a file; 
makes several windows split among the buffers as specified. 
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Overview 



The commands described in this section are unlike most other 
Zmacs commands. Their main business is not manipulating buffers 
and their contents, but rather files out in a file system. First we 
discuss some commands for dealing with files, then we describe 
buffer and file attributes, and finally we explain Dired Mode, a 
special Zmacs mode for directory editing. 



Creating a Directory 

Create Directory (n-x) 



Example 



Creates a new directory. It prompts for a directory name, using 
the standard conventions for defaults. For consistency between 
hierarchical and nonhierarchical file systems, you specify the 
directory to be created as the directory component of a pathname. 
That is, you must end the directory name with whatever delimiter 
or separator is appropriate for the host. 



Host Directory string Result 

TOPS-20 <A.B.O Creates directory C 

Multics >udd>Sun>Luna>z> Creates directory z 

Lisp Machine >sun>luna>b> Creates directory b 

UNIX /usr/jek/new/ Creates directory new 

Currently, the file servers for VAX/VMS and TOPS-20 can fail to 
create directories, due to missing options. 



Listing Files in a Directory 

List Files (n-X) 



Prompts for the name of a directory and displays the names of all 
the files in that directory. 

The file names are mouse sensitive. Pointing at a file name and 
clicking left is the same as doing a c-x c-F (Find File) on that file. 
Clicking right pops up a menu with three items: 

Load Loads the file into the Lisp world. The file must be 

either a Lisp source file or a compiled Lisp (bin) file. 

Find Reads the file into an editor buffer. 

Compare Compares the file with its most recent version and 

prints the differences. 
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Displaying the 
Contents of a Directory 

c-x c-D Display Directory 

Displays the directory of the file in the current Zmacs buffer, c-x 
c-D does not ask for a directory but lists files with the same host, 
device, directory, and name as the file in the current buffer. It 
lists files with any type and version. With a numeric argument, it 
prompts for a directory to list and lists that directory. 

The heading of the directory listing is mouse sensitive; clicking left 
on it selects a Dired buffer containing that directory listing. 

c-u c-x c-D does the same thing as List Files, except that it gives 
more details about each file. 

Show Directory/View Directory 

Show Directory (n-x) 

View Directory (n-X) 

Prompts for the name of a directory and and displays the directory 
contents for viewing only in the typeout window. If there is more 
than a screenful, it pauses between screenfuls displaying a --MORE-- 
message at the bottom. 

SPACE Displays the next screenful. 

BACKSPACE Displays the previous screenful. 
RUBOUT Exits. 

Anything else exits and is executed as a command. 

Viewing a File 

Show File/View File is for when you just want to look at a file, not 
edit it. 

Show File (n-X) 

View File (n-X) 

Prompts for the name of a file and displays the file contents for 
viewing only in the typeout window. If there is more than a 
screenful, it pauses between screenfuls displaying a --MORE-- 
message at the bottom. 

SPACE, c-y, scroll Displays the next screenful. 

BACKSPACE, n-V Displays the previous screenful. 

RUBOUT Exits. 
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Anything else exits and is executed as a command. 



Viewing the 
Properties of a File 

View File Properties (n-x) 



Prompts for the name of a file and displays all the properties of the 
file that are maintained by the file system on which it resides. 
These are the properties such as creation date and time, author, 
time of last access, and length. For files on a Lisp Machine file 
system, it displays user-defined properties as well. 

It prompts for a file specification, which it merges with the current 
default to form the pathname. Wildcards are not accepted; this 
must correspond to a unique file or directory name. 



Changing the 
Properties of a File 

Change File Properties (n-X) 



Edits the properties of a file. Properties are the qualities of the file 
that are maintained by the file system on which it resides, such as 
creation date and time, author, time of last access, and length. For 
files on a Lisp Machine file system, this means user-defined 
properties as well. It prompts for the name of a file and pops up a 
choose-variable-values window, allowing you to alter various 
properties of the file. The exact properties that can be altered 
depend on the file system, but they might include: 

• Generation (version) retention count 

• Author 

• Creation, modification, and reference dates 

• Protection flags 

• Other file-associated information 



Hardcopying a File 

Hardcopy File (n-x) 



Sends a file to the local hardcopy device for printing. 



Renaming a File 

Rename File (n-x) 



Renames one or more files. It prompts for the name of a file and 
then asks for a new name for that file. It renames the specified 
file with that new name. 

If the source file specification is wild, the target file specification 
must also be wild. 
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Copying a File 
Into Another 

Copy File (n-X) 



Examples 



Copies any type of file to another specified file. 

Prompts from the minibuffer for the names of two files and copies 
the contents of the first into the second. In file systems supporting 
multiple versions, this creates a new version of the second file 
whose contents are identical to those of the first. 

Copy File determines whether the source file is a character file or a 
binary file and copies the file appropriately. Different file systems 
sometimes use different character sets, and if the file is a character 
file, character translations have to be done (for example, on some 
hosts Return characters have to be converted into a carriage return 
and a line feed). 

The numeric argument controls copying of attributes and 
properties. With no numeric argument, it copies creation date and 
author and determines the mode (binary or character) of copy by 
the file being copied. To force mode, or suppress author or creation 
date copying, supply a numeric argument created by adding the 
values corresponding to the descriptions below: 

1 Force copy in 16-bit binary mode. 

2 Force copy in character (text) mode. 
4 Suppress copy of author. 

8 Suppress copy of creation date. 



For example, to suppress author and creation date for copying: 
c-12 Copy File (n-X) 

Use wildcard pathnames to specify groups of files for copying. For 
example, to copy all files in the subdirectory mine: 

F:>program>mine>*.* 

If the source file specification is wild, the target file specification 
must also be wild. 
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you type: n-X Copy File 

Zmacs: Copy File from: 
you type: scrc:<lmfs>*.l*sp;0 

(Copies all the newest .LISP and .LSPs) 
Zmacs: to: 
you type: ff :>sys-hold>scrc-sources>old-*.*.* 
Zmacs: SCRC:<LMFS>TEST.LSP.3 is copied into 

ff :>sys-hold>scrc-sources>old-test.lisp.3 

SCRC:<LMFS>FILES. LISP. 147 is copied into 

f f : >sys-hol d>scrc-sources>ol d-f i 1 es . 1 i sp . 147 

Note that .LSP gets mapped into .lisp because Copy File uses 
canonical types when the type of the target pattern is :wild. 

This command can copy file authors and creation dates, when the 
target operating system supports setting these attributes. This 
action is not the default. 



Creating Links to Files 

Create Link (n-x) 



Creates a link to a file. It prompts in the minibuffer for the names 
of two files as arguments; first the name of the link, then the 
name of the target pointed to by the link. 



Deleting Files 



Delete File (n-X) 

Deletes a file. It prompts in the minibuffer for a file name, which 
can be wild. With a wild name as an argument, deletes multiple 
files. It lists the files that would be deleted and requires that you 
confirm the list. It deletes the files, showing any errors that occur 
but continuing rather than halting. Displays a message in the 
minibuffer if the specified file does not exist. 

Deleting Multiple Versions 

Reap File (n-x) 

This command works in file systems supporting multiple versions. 
It prompts for the name of a file (not including version number) 
and deletes excess or temporary versions of the specified file, 
keeping the most recent n files. Any numeric argument specifies 
the number of versions to keep. With no numeric argument, the 
default keeps two versions and deletes any excess. It prompts for 
confirmation of files being deleted. 

Note: 
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• To specify file types to be automatically marked for deletion, 
change the value of the variable zwei:*temp-file-type-list*, 
which contains a list of these files. Its default values are: 
"memo", "xgp", "@xgp", "unfasl", "output", "olrec" and "press". 
This variable also accepts the value tanything, which can be any 
file type. 

• To alter the default number (2) of versions to be kept, change 
the value of the variable zwei:*file-versions-kept* to any 
:fixnum. 

Clean Directory (n-x) 

Deletes excess versions or temporary file types in the specified 
directory. The default for excess versions is more than two. It 
prompts for confirmation of files being deleted. With a numeric 
argument n> it deletes excess versions greater than n. 

Excess is defined by the value of the Zmacs variable File Versions 
Kept or by the numeric argument. The temporary file types are 
defined by the Zmacs variable Temp File Type List. It accepts 
wildcards in the file name specification. (For descriptions of Zmacs 
variables: See the section "How to Specify Zmacs Variable 
Settings", page 210.) 



137 
March 1985 Zmacs Manual 

Buffer and File Attributes 



Attributes 



Each buffer and generic pathname has attributes, such as Package 
and Base, which can also be displayed in the text of the buffer or 
file as an attribute list. An attribute list must be the first 
nonblank line of a file, and it must set off the listing of attributes 
on each side with the characters -*-. If this line appears in a file, 
the attributes it specifies are bound to the values in the attribute 
list when you read or load the file. 



How They Work 



Suppose you want your new program to be part of a package 
named graphics that contains graphics programs. In this case, 
you want to set the Package attribute to graphics in three places: 
the generic pathname's property list; the buffer data structure; and 
the buffer text. Here are two ways to make the change: 

• If the package already exists in your Lisp environment, use Set 
Package (n-x) to set the package for the buffer. The command 
asks you whether or not to set the package for the file and 
attribute list as well. You can use this command to create a new 
package. 

• Use Update Attribute List (n-X) to transfer the current buffer 
attributes to the file and create a text attribute list. Edit the 
attribute list, changing the package. Use Reparse Attribute List 
(n-x) to transfer the attributes in the attribute list to the file 
and the buffer data structure. If the package you specify by 
editing the attribute list does not exist in your Lisp environment, 
Reparse Attribute List asks you whether or not to create it with 
default characteristics. 



Attribute- 
manipulating Commands 

Update Attribute List (m-x) 



Updates the attribute list (-*- line) of the buffer. It creates or 
updates the attribute list of the file, using the current set of 
parameters. A new attribute list inherits the default base (10) and 
the default syntax (Zetalisp) plus the Package, Mode, Backspace, 
and Fonts attributes of the current buffer. It includes the 
Backspace and Fonts attributes in the line only if they have values 
other than the defaults. It does not change other attributes in an 
existing mode line. 

Reparse Attribute List (n-x) 

Reparses the attribute list (-*- line) of the buffer. It finds the 
attribute list for the buffer and processes it to set up the 
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environment that the line specifies. It changes the major mode, 
package, base, and so on, as necessary. When you edit the 
attribute list, you should then use this command to make the 
changes take effect in Zmacs. The changes take effect both for the 
editor buffer and for the file that the buffer is editing. 



Example 

Suppose the package for the current buffer is user and the base is 
8. You want to create a package called graphics for the buffer 
and associated file. You also want to set the base to 10. If no 
attribute list exists, use Update Attribute List (n-x) to create one 
using the attributes of the current buffer. An attribute list appears 
as the first line of the buffer: 

;; ; -*- Mode: LISP; Package: USER; Base: 8 -*- 

Now edit the buffer attribute list to change the package name from 
USER to GRAPHICS and to change the base from 8 to 10. Use Reparse 
Attribute List (n-X). The command queries: 

The file belongs in package GRAPHICS, which does not exist. 
Create it with default characteristics, 
Try again, or Use another package? (C, T, or U) 

Answer C to create the new package. The package becomes 
graphics and the base 10 for the buffer and the file. 

File Attribute Checking 

Zmacs notes errors in file attribute lists and warns you when it 
finds an unknown attribute. It goes ahead and ignores the 
unknown attribute in the list. The purpose of the warning is 
simply to help you detect misspellings. 

Setting the Package 

Set Package (m-X) 

Changes the package associated with the buffer. It prompts for a 
new package, offering to create the package if necessary. Forms 
that are read from the buffer are read in that package. (The 
default value for this attribute is user.) 

You can have any package as the default package by specifying it as 
the value of the Zmacs variable Default Package. (For descriptions 
of Zmacs variables: See the section "How to Specify Zmacs Variable 
Settings", page 210.) You can set the variable in your init file by 
using the internal form of its name. (See the section "Creating an 
Init File", page 213.) 

For example, in your init file: 
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(log in- forms 

(setf zwei:*defau It-package* (pkg-find-package "tv"))) 

If you set the variable to nil, it sets the default to the package 
from the previous buffer. 

Information about the package attribute exists in four places. Set 
Package offers to set the package for the generic pathname 
attribute list and updates the attribute line in the buffer when you 
answer Yes to: 

Set it for the file and attribute list too? 

Your answer affects the various versions of the package attribute as 
follows: 



Location 


iryii 


"N" 


Generic pathname 


changes 


same 


Buffer property 


changes 


changes 


Buffer text 


changes 


same 


Current package 


changes 


changes 



The system is informed that the file belongs to the specified 
package. If you are not sure what to answer, say Yes. The global 
variable zwei:*set-attribute-updates-list* controls this query. Its 
default value is task. Setting the variable to t means Yes; nil 
means No. 

Base and Syntax Defaults 

The default value of base and ibase is 10. If you have been 
writing code that has a Base attribute in the mode line, you should 
not experience any difficulties. However, in order to help avoid 
problems in general, changes have also been made to the editor and 
compiler: 

• In the mode line (the -*- line in Lisp source files) are the Base 
and Syntax attributes. The base can be either 8 or 10 (default). 
The syntax of a program can be either Zetalisp or Common-Lisp. 

• If there is a Base attribute, but no Syntax attribute, the syntax 
is assumed to be Zetalisp. 

• If there is a Syntax: Common-Lisp attribute, and no Base 
attribute, the base is assumed to be 10. 

• If there is neither a Base nor a Syntax attribute, Base is 
assumed to be the default base (10) and the syntax is assumed to 
be Zetalisp. Furthermore, a warning is issued to the effect that 
there is neither a Syntax nor a Base attribute. You should edit 
your program accordingly. With most programs, the Zmacs 
command Update Attribute List (n-x) will add the appropriate 
attributes to the mode line, following the above defaults. 
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Setting the Syntax 
for Symbolics 
Common Lisp 



If you use the new Symbolics Common Lisp (SCL), you must 
explicitly set the syntax in the file attribute line (formerly, Zetalisp 
was the implicit default). For more information about SCL: See 
the section "Introduction to Symbolics Common Lisp" in Reference 
Guide to Symbolics-Lisp. 

The file attribute line of a Common Lisp file should be used to tell 
the editor, the compiler, and other programs that the file contains a 
Common Lisp program. The following file attributes are relevant: 

Syntax The value of this attribute can be Common-Lisp 

or Zetalisp. It controls the binding of the 
Zetalisp variable readtable, which is known as 
*readtable* in Common Lisp. 

Package user is the package most commonly used for 

Common Lisp programs. You can also create 
your own package. Note that the Package file 
attribute accepts relative package names, which 
means that you can specify user rather than 
cl-user. 

The following example shows the attributes that should be in an 
SCL file's attribute line: 

;;; -*- Mode:Lisp; Syntax: Common- Lisp; Package: CL-USER -*- 

Set Syntax (n-X) 

Changes the buffer into Common Lisp syntax or Zetalisp syntax. It 
asks whether to update the attribute list (-*- line) of the buffer. If 
you answer yes, it creates or updates the attribute list of the file, 
using the current set of parameters, if any. It does not change 
other attributes in an existing mode line. 



Other Set 

Commands for 

File and Buffer Attributes 

Each of the file attributes has a Set command associated with it. 
You have two choices when you want to change an attribute for a 
file: 

• Edit the text of the buffer and then use Reparse Attribute List. 

• Use the relevant Set command and answer Y to its query. The 
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meanings for Y and N are the same as for the Set Package 
command (except that only the Set Package command affects the 
current package). 



Update Attribute 
List Query 



The Set commands use the value of the global variable 
zwei:*set-attribute-updates-list* to determine whether to query 
you about updating the file attribute list. The default value for the 
variable is :ask; set to nil to suppress the query. 

Value Meaning 

:ask Always asks whether to update the attribute list. 

nil Never updates the attribute list. 

t Always updates the attribute list. 



Set attribute (n-X) 

where attribute is one of the following: Backspace, Base, Default 
File Name, Fonts, Key, Lowercase, Nofill, Package, Patch File, 
Syntax, Tab Width, Variable, Visited File Name, or Vsp. It sets 
attribute for the current buffer. It queries whether or not to set 
attribute for the file and in the text attribute list. 

Attribute Descriptions 

The following table describes some of the attributes, their associated 
Set commands, and the default value for the attribute. 



Backspace The Set Backspace command (default value nil) 

controls whether a backspace character in a file 
displays as the word "back-space" with a lozenge 
around it or performs the backspace. The 
default is the lozenge form. 



Base The Set Base command (default value 10) 

specifies the value of ibase that the Lisp reader 
uses when reading forms from the file. Thus, 
Base controls the ibase used when you evaluate 
or compile parts of the buffer, and controls the 
value of base for printing during evaluating all 
or part of the buffer. This value does not affect 
the values of either base or ibase in the Lisp 
Listener you get by using SUSPEND. 
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Fonts 



Lowercase 



The Set Fonts command (default value nil) 
changes the set of fonts to use. It reads a 
sequence of font names separated by spaces, 
commas, or both from the minibuffer. 

The Set Lowercase command (default value nil) 
means that the file being edited is intended to 
contain lowercase code or text. When the 
Lowercase attribute is nil (that is, not present), 
whatever case handling you specify prevails. To 
automatically uppercase code, use the following in 
your init file: 

((login-forms 
(setf zwei : lisp-mode-hook 
'zwei :electric-shift-lock-if-appropriate)) 



(See the section "Creating an Init File", page 
213.) When the Lowercase attribute is anything 
but nil (you answer Y to its query), the Electric 
Shift Lock Mode is never turned on 
automatically. 
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Nofill 



The Set Nofill command has a default value of 
nil, which means that whatever autofilling 
behavior you specify prevails. When Nofill is 
anything else (you answer Y to its query), it 
means that autofilling is not appropriate for 
people who specify the mode of "autofilling if 
appropriate". 

Use Nofill sparingly. Setting it means that 
everyone who edits the file has to be satisfied 
with Auto Fill Mode being off by default. In 
most cases, it is more reasonable to let an 
individual user's preferences prevail. It is useful 
for files that are not plain text, such as mailing 
lists, where you need to avoid spurious line 
breaks. 

To have autofilling turned on by default, use the 
following in your init file (See the section 
"Creating an Init File", page 213.): 

(log in- forms 
(setf zwei: text-mode-hook 
'zwei :auto-fill-if-appropriate)) 

People who do not want it never get it by 
default. 



Patch-File 



Tab-Width 



Vsp 



The Set Patch File command has a default value 
of nil, which means that the file does not 
contain patches. When a file is classified as 
containing patches (you answer Y to its query), 
fdefine does not warn about functions being 
redefined during loading. Classifying something 
as a patch file also affects Edit Definition (which 
prefers files that are not patches) and defvar 
(which becomes setf). 

The Set Tab Width command (default 8 
characters) specifies how many spaces the editor 
uses between "tab stops". 

The Set Vsp command (default 2 pixels) specifies 
the vertical spacing (in pixels) between the text 
lines of an editor window. It specifies the 
distance between the descenders of one line and 
the ascenders of the next. 
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Dired Mode 

Overview 

There is a special Zmacs mode, called Dired, just for doing 
housekeeping in a directory. In this mode, you see the names of all 
the files in a directory at once, and can manipulate these files in 
various ways. 

Entering Dired 

The following commands specify a directory to manipulate and enter 
Dired mode. 

Dired (n-x) 

Edit Directory (n-X) 

Prompts for a wildcard file specification for files contained in the 
specified directory. The default edits all files in the current 
directory by specifying wild name, type, and version. You must 
type the pathname in the form acceptable to your host system. 

c-X D Dired 

Edits the files in the directory that contains the current file. 

With a numeric argument of 1, shows files with the same host, 
device, directory, and name as the file in the current buffer. It 
lists files with any type and version. 

With a c-U argument, it prompts for a wildcard file specification 
showing the name of a directory to edit. 

The Dired Display 

When you go into Dired mode, Zmacs creates a special buffer that 
contains the names of the files that are under consideration, as well 
as some auxiliary information pertaining to those files. In a typical 
Dired buffer, each line describes a single file and lists the following 
information, from left to right: 

• An indicator (D) that shows if the file has been marked for 
deletion or is already deleted 

• The physical volume of the file (on some hosts) 

• The name of the file 

• The length of the file in blocks (where the length of a block is 
system-dependent) 

• The length of the file in bytes, followed by the byte length in 
bits, enclosed in parentheses 

• ! if the file has not been backed up to tape 

• $ if the file has been marked against reaping 

• @ if the file has been marked against deletion 

• The file's creation date 
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• The file's creation time 

• The date the file was last referenced, enclosed in parentheses 

• The author of the file 

• Optionally, the name of the last user to read the file 

If there are too many files to be displayed in one screenful, the 
Zmacs window looks only at one section of the directory at a time 
(although the buffer does contain the names of all the files). 

The files are arranged in alphabetical order by name. 

Updating the Display 

Use the Revert Buffer (ro-x) command to update a Dired display. 
(See the section "Re-reading a File Into the Buffer", page 121.) 
After using Dired commands (or native host commands) to perform 
operations on files in your directory, invoke Revert Buffer, which 
reexecutes Dired with the default directory name and re-reads the 
updated directory into the buffer. 

Dired Commands 

Dired mode has its own command table (comtab) for manipulating 
the files whose names are displayed. These commands are 
described in this section. All invocations given in this section are 
with respect to the Dired comtab and do not apply to regular 
Zmacs. 

You use Dired by moving the cursor around to various lines and 
then specifying operations to be performed on the file listed on that 
line (the current file, while in Dired Mode). 

Most Dired commands schedule some action for the future rather 
than performing it instantly. For example, when you want to 
delete a file using Dired, you move the cursor to the line describing 
that file and type D. Rather than deleting the file immediately, 
Dired marks the file for deletion. The deletion actually happens 
when you leave Dired mode and confirm your request. (See the 
section "Getting Out of Dired", page 147.) 

Some of the commands in Dired mode take numeric arguments. 
You type numeric arguments in exactly the same way as you do in 
Zmacs proper, except that you do not have to hold a modifier key 
down while typing the argument — just typing the number 
suffices. 
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Command Summary 

The following table summarizes the Dired commands: 



Character 
RUBOUT 
SPACE 
i 



G 

TlH 

L 
TIN 



Action 

Undeletes file above the cursor. 

Moves to the next file. 

Moves to the next file that is not backed up. 

Complements the Don't Reap ($) flag. 

Describes the attribute list of this file. In text files, 
this is the -*- line of the file. In compiled Lisp files, 
it includes information about the compilation as well. 

Changes properties of current file. 

Complements the Don't Delete (@) flag. 

Compares this file with the newest version (Source 
Compare). 

Queues this file for function application. 

Copies this file to someplace else. 

Marks the file for deletion (K, c-D, c-K are 
synonyms). 

Edits the file in a buffer, or runs Dired if the line is 
a subdirectory name. 

Sets and enforces the generation retention count. 

Marks excess versions of the file for deletion 
(argument means whole directory). 

Loads the file into Lisp. 

Moves to the next file with more than n versions 
(see the Zmacs variable File Versions Kept). (For 
descriptions of Zmacs variables: See the section 
"How to Specify Zmacs Variable Settings", page 210.) 

Prints the file on the standard hardcopy device. 

Exits. It shows the files marked for deletion and 
prompts for confirmation. The exit display marks 
files that have special status, using the following 
marks: 
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: a link 

> most recent version 

$ file marked for not reaping 

! file not backed up 

R Renames this file to something else. 

U Undeletes either the file on the current line or the 

file on the line above. 

V Views the file without creating a buffer (using View 

File conventions). 

X Executes an extended command (same as n-x). 



Default 
Pathnames in Dired 

When the current buffer is a Dired buffer, and you execute an 
editor command that accepts a file name as an argument, the 
default file name is the file name that appears on the line of the 
Dired buffer that point is on. 

This makes it easier to do things to the file that you are currently 
operating on in Dired. For example, you can move point to some 
line, do Compile File (n-x), and the command defaults to that file 
name. 

Getting Out of Dired 

Q Dired Exit 

END 

Leaves Dired mode. It prints the names of files marked for various 
actions and gets your final confirmation that these actions are really 
to be performed. 

At this point the available options are: 

Y Delete but do not expunge, also doing any other marked 

actions. 

N Go back to Dired. 

Q or X Abort out of Dired. 

E Delete files and expunge directory. This is meaningful 

for file systems in which there is undeletion, such as 
TOPS-20, TENEX, and the Lisp Machine file system. 
This command is useful if you use Dired to free up disk 
space, since the disk space is not deallocated until the 
directory is expunged. 



148 

Text Editing and Processing 



March 1985 



Dired Mode, cont'd. 



Dired Exit performs those actions and returns to the previous 
buffer. 



ABORT 



Dired Abort 



Leaves Dired mode at once, without performing any actions on 
marked files. You can also just switch to another buffer. 



Online 

Documentation 
for Dired 



Dired Menu 



If you do not have a manual and cannot remember what the 
commands do, just press HELP. 



7 

HELP 



Dired Help 



Displays a short table explaining the Dired commands. 



Click right in Dired to display the Dired menu, which offers to 
perform the following actions on the listing: 

Sort by reference date (up) 
Sort by reference date (down) 
Sort by creation date (up) 
Sort by creation date (down) 
Sort by file name (up) 
Sort by file name (down) 
Sort by file size (up) 
Sort by file size (down) 
Dired Automatic 
Dired Automatic All 
Dired Change File Properties 
Dired Describe Attribute List 

See the section "Deleting Multiple File Versions in Dired", page 151. 
See the section "Changing File Properties in Dired", page 149. See 
the section "Viewing File Attributes in Dired", page 149. 



Loading a File in Dired 

Load File (m-X) 



Loads a file, possibly saving and compiling it first. It prompts for a 
file name, taking the default from the current buffer. It checks to 
see if the file you are compiling corresponds to a buffer and offers 
to save that buffer if it is modified. If the .bin file is older than 
the .lisp file, it offers to compile the file first. If the typeout 
window displays any compiler warnings, Load File asks if you really 
want to load the file despite the compiler warnings. 
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Moving Around in Dired 

SPACE Down Real Line 

c-N 

Moves point to the next line (same as in regular Zmacs). With a 
numeric argument of n, it moves point forward n lines. 

c-P Up Real Line 

Moves point to the previous line (same as in regular Zmacs). With 
a numeric argument of n y it moves point backward n lines. 

Viewing File 
Attributes in Dired 

Dired Describe Attribute List 

This command is also available on the pop-up menu that you get 
when you click right in Dired. It prints out the contents of the 
attribute list of the current file (the one where point is). It works 
for character files and compiled files. 

Changing File 
Properties in Dired 

Dired Change File Properties 

This command is also available on the pop-up menu that you get 
when you click right in Dired. It edits the properties of the 
current file. These properties are the qualities of the file that are 
maintained by the file system on which it resides, such as creation 
date and time, author, time of last access, and length. For files on 
a Lisp Machine file system, this means user-defined properties as 
well. It pops up a choose-variable-values window, allowing you to 
alter various properties of the file. The exact properties that can be 
varied depend on the file system, but they might include: 

• Generation (version) retention count 

• Author 

• Creation, modification, and reference dates 

• Protection flags 

• Other file-associated information 

Viewing and 
Editing File 
Contents in Dired 

You might want to look at the contents of a file before deciding 
what to do with it. You might also want to read the file into a 
buffer and edit it. 
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V Dired View File 

Displays the contents of the current file on the typeout window. 

Use this command when you just want to skim the contents of the 
file, not edit it. You can move forward while viewing with sprce 
and move backward with BACKSPACE. 

E Dired Edit File 

Reads the current file into a Zmacs buffer and selects that buffer. 
You are then back in normal Zmacs and can edit the file normally. 
When you want to return to Dired mode, just use the c-n-L 
command to reselect the Dired buffer. 

Comparing Recent 
Versions of Files 
in Dired 

Often before deciding whether or not to delete a file, you want to 
find out exactly how extensive the differences are between the file 
and its most current version. 

= Dired Srccom 

Compares the current file with its most recent version and displays 
the differences on the typeout window. With an argument of c-u, 
it asks what version to compare it to. 

Copying and 
Renaming Files 

C Dired Copy File 

Copies the current file. It prompts for the new pathname, 
displaying the default pathname. 

R Dired Rename File 

Renames the current file. It prompts for the new pathname, 
displaying the default pathname. 

Marking Files for Deletion 

D Dired Delete 

K 

c-D 

c-K 

Marks the current file for deletion. Dired puts a D in the first 
column to show that the file has been so marked. 



151 
March 1985 Text Editing and Processing 

Dired Mode, cont'd. 



With a numeric argument of n, it marks the next n files for 
deletion. 

Sometimes you mark a file for deletion by mistake. Here is how 
you recover from this error: 

u Dired Undelete 

u takes one of two actions: 

1. If the current file is marked for deletion, printing, or a function 
application (with a D, P, or A), reprieves it. 

2. In file systems with soft deletion, u marks a deleted file for 
undeletion. 

In either case, U removes the D, P, or A next to the file. If the 
current file is not marked with D, P, or A, U reprieves the file on 
the immediately preceding line, positioning point on that line. 

With a numeric argument of n, it reprieves the files on the next n 
lines including the current line. 

RUBOUT Dired Reverse Undelete 

Reprieves the file on the preceding line. 

With a numeric argument of n> it reprieves the files on the previous 
n lines including the current line. 

Deleting Multiple Versions 

If you are using Dired for housekeeping purposes, the following 
commands are useful: 

N Dired Next Hog 

Moves point to the next file with superfluous versions. Superfluous 
is defined by the value of the Zmacs variable File Versions Kept 
(whose default is 2) or by a numeric argument. (For descriptions of 
Zmacs variables: See the section "How to Specify Zmacs Variable 
Settings", page 210.) 

H Dired Automatic 

This command is also available on the pop-up menu that you get 
when you click right in Dired. It marks all the superfluous versions 
of the current file for deletion. With an argument of c-U, it marks 
superfluous versions of all files in the Dired buffer. 
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Setting 
Generation 
Retention Count 

G Dired Set Generation Retention Count 

Sets and enforces the generation retention count on this group of 
files, which specifies how many versions to save (that is, deletes 
multiple versions). 

With a numeric argument n, sets it to n versions. With no 
numeric argument, prompts for a number in the minibuffer. An 
argument of zero means save all versions. Enforce means mark for 
deletion or undeletion. 

Protecting Files 
From Being Reaped 

In addition to keeping other users aware of protected files, 
protection features can also inform the system itself. Some file 
systems have automatic reaping facilities that go into action when 
storage becomes scarce. Most such systems have a don't reap bit 
associated with each file; use it to protect only your most vital files. 

$ Dired Complement No Reap Flag 

Complements the Don't Reap flag associated with the current file; 
Dired displays the flag as $ between the length and date on that 
line. With a numeric argument of n, it complements the flag on 
the next n files, including the current one. 

Protecting Files 
From Being Deleted 

e Dired Complement Dont Delete Flag 

Complements the Don't Delete flag associated with the current file; 
Dired displays the flag as @ between the length and date on that 
line. 

With a numeric argument of n, it complements the flag on the 
next n files, including the current one. 

Finding Files That 
Have Not Been 
Backed up 

Many file systems have tape backup facilities so that files can be 
copied onto tape against the possibility of a file system disaster. 
These systems almost always associate a bit with each file that is 
set when the file is created or modified and cleared when it is 
backed up to tape. 
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! Dired Next Undumped 

Moves point forward to the next file that has not yet been backed 
up; Dired displays the flag as ! between the length and date on 
that line. 

Marking Files to 
Be Hardcopied 

You might want to obtain a hardcopy of a group of related files. 
Dired allows you to mark files to be hardcopied as well as to be 
deleted. 

P Dired Hardcopy File 

Marks the current file for printing. Dired puts a P in the first 
column to show that the file has been so marked. 

With a numeric argument n y marks the next n files for printing. 

Applying 
Arbitrary 
Functions to Files 

Very occasionally, you want to perform some operation on selected 
files in your directory for which there is no Dired command 
provided. When this occurs, you can write up the operation that 
you want to perform as a Lisp function, whose single argument is 
the pathname of the file. The following command is relevant: 

fl Dired Apply Function 

Marks the current file for having an arbitrary function applied to it. 
Dired puts a A in the first column to show that the file has been 
so marked. With a numeric argument of n, it marks the next n 
files, including the current one. 
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Major Editing Modes 



Overview 

Whenever you are editing some text, some set of modes is in effect. 
The buffer is always associated with one major mode that tells the 
editor what kind of document is being edited. A major mode has 
the following characteristics: 

• It has its own distinct set of key bindings. 

• It affects groups of related language-specific items, such as 
delimiter characters and indentation rules. 

The major modes are listed below. You can establish the mode: 

• By turning it on using the prefix m-X followed by the name of 
the mode. For example, to invoke Lisp Mode, type: n-x Lisp 
Mode. 

• By setting it in the attribute list. See the section "Buffer and 
File Attributes in Zmacs", page 137.) 

• By having Zmacs do it for you when you read a file with c-x 
c-F. It recognizes the type component of the pathname of the 
file (for example, folon.lisp) and puts the buffer in the 
corresponding mode. 

Fundamental Mode 

Fundamental Mode enters Zwei's fundamental mode (the default 
mode). 



Lisp Mode 



Text Mode 



Note 



Lisp Mode sets things up for editing Lisp code. It puts Indent-For- 
Lisp on TAB. 

When you read a file that has a Lisp file type into the buffer, if 
that file does not begin with an attribute line containing Base and 
Syntax attributes, Zmacs warns that the file "has neither a Base 
nor a Syntax attribute" and announces that it will use the defaults, 
Base 10 and Zetalisp. See the section "Buffer and File Attributes". 



Sets things up for editing English text. It puts Tab-To-Tab-Stop 
on TAB. 



Zmacs supports Fortran Mode as a part of FORTRAN 77, the 
separately priced software product. For more information, see the 
User's Guide to the FORTRAN 77 Tool Kit. 
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Macsyma Mode 



Macsyma Mode enters a mode for editing Macsyma code. It 
modifies the delimiter dispatch tables appropriately for Macsyma 
syntax, makes comment delimiters /* and */. It puts Indent- 
Relative on TAB. 



Midas Mode 



Bolio Mode 



Teco Mode 



Pll Mode 



Midas Mode sets things up for editing PDP-10 assembly language 
code. 



Bolio Mode sets things up for editing Bolio source files. It is like 
Text Mode, but also makes c-n-iV, c-n-:, and c-n-* insert font 
characters, and makes word-abbrevs for znil and zt. 



Teco Mode sets things up for editing TECO. It makes comment 
delimiters be !* and *!. It puts Indent-Nested on TAB, Forward- 
Teco-Conditional on n-' , and Backward-Teco-Conditional on n-]. 



Pll Mode sets things up for editing PL/1 programs. It makes 
comment delimiters /* and */, and puts Indent-For-Pll on TAB, Roll- 
Back-PU-Indentation on c-n-H, and Plldcl on c-s. Underscore is 
made alphabetic for word commands. 



Electric Pll Mode 

Electric Pll Mode sets things up for editing PL/1 programs. It does 
everything Pll Mode does: it makes comment delimiters /* and */, 
puts Indent-for-PU on TAB, Roll-Back-Pll-Indentation on c-n-H, , 
and Plldcl on c-s. Underscore is made alphabetic for word 
commands. In addition, j is PU-Electric-Semicolon, : is Pll-Electric- 
Colon, # is Rubout, @ is Clear, \ is Quoted Insert. 
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Changing Case 



Overview 

Zmacs offers extended commands that convert the case of the code 
for words, regions, and buffers. 

Changing Case of Words 

n-C Uppercase Initial 

Puts next word in lowercase, but capitalizes initial character. With 
an argument, it capitalizes that many words. 

n-L Lowercase Word 

Puts next word in lowercase. With an argument, it puts that 
many words in lowercase. 

n-U Uppercase Word 

Puts next word in uppercase. With an argument, it puts that 
many words in uppercase. 

Changing Case of Regions 

c-X c-U Uppercase Region 

Uppercases the region. 

c-X c-L Lowercase Region 

Lowercases the region. 

Uppercase Code in Region (n-x) 

Converts all code (not comments, strings, or quoted characters) to 
uppercase. This gives the same effect as retyping that text while 
in Electric Shift Lock Mode. It operates on the region if there is 
one, otherwise it operates on the current definition. 

Lowercase Code in Region (n-x) 

Converts all code (not comments, strings, or quoted characters) to 
lowercase. It operates on the region if there is one, otherwise it 
operates on the current definition. 

Changing Case of Buffers 

Uppercase Code in Buffer (n-X) 

Converts all code (not comments, strings, or quoted characters) to 
uppercase. This gives the same effect as retyping that text while 
in Electric Shift Lock Mode. It queries for a buffer name (the 
default is the current buffer) and operates on that buffer. 
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Lowercase Code in Buffer (m-x) 

Converts all code (not comments, strings, or quoted characters) to 
lowercase. It queries for a buffer name (the default is the current 
buffer) and operates on that buffer. 
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Overview 



Proper indentation helps make complicated Lisp programs readable. 
Indentation should reflect the structure of a program. An 
expression should be indented so that its subforms are easily 
identifiable, and so that a function can be related to its arguments 
by eye, without counting parentheses. 

The indentation commands work in any Zmacs major mode; the 
TAB key indents differently depending on the mode. When you give 
an indent command an argument of n> n equals the number of 
Space characters in the default font. 



Indenting Current Line 

TAB 



In Lisp mode, the TAB key indents the current line of Lisp code 
correctly with respect to the line above it. (In most other modes, 
tab inserts a Tab character.) Point remains fixed with respect to 
the code. 

With a numeric argument n, it indents the next n lines including 
the current one, and leaves point at the n+lst line. 

c-TRB Indent Differently 

Tries to indent this line differently. If called repeatedly, it makes 
multiple attempts. 

n-TAB Insert Tab 

Inserts a Tab character, even in Lisp Mode, in the buffer at point. 

c-n-TAB Indent For Lisp 

Indents this line to make ground (indented) LISP code, even in a 
mode other than Lisp Mode. A numeric argument specifies the 
number of lines to indent. 

Indentation in 
loop Macros 

The loop Indentor 

Zwei now indents code within a loop macro in a more attractive 
way than it did in the past. The TAB key indents the code while 
recognizing and dealing appropriately with loop keyword clauses. 
This new indentation style is a major incompatible change in the 
Zmacs user interface for writing Lisp code. You might want to 
know how to turn it off because it indents new code in a style that 
is inconsistent with existing code. 
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To turn off the new loop indentor, including the following flag in 
your init file: 

(SETF ZWEI:*INHIBIT-FANCY-LOOP-INDENTATION* T) 

The initial value for this flag is nil; t reverts to the old-style 
indentor. 

How to Use the 

loop Indentor 

Use the loop indentor the same way as always: type a token on a 
line of code inside a loop and then press TAB, which correctly 
indents the code. 

The usual sequence: 

LINE finally TAB 

(substitute any other loop word for finally) reindents based on the 
new knowledge that this is a finally line rather than a body line. 
The loop indentor always ignores comments. 

Loop Indentor Example 1 

The right indentation sometimes depends on forms after the line 
you are indenting. For example: 

(loop for a being the array-elements of b 
; ; comment 
do (frob a)) 

Press TAB at the end of the comment line and: 

(loop for a being the array-elements of b 
; ; comment 
do (frob a)) 

happens because the loop indentor anticipates that you might 
instead be doing this: 

(loop for a being the array- elements of b 
; ; comment 
using (sequence b) (index i) 
do (frob a)) 



Loop Indentor Example 2 

The loop indentor second guesses on a few things, but gets them 
right after you type a token on a line and press TAB. For example: 
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(loop when x 
do (y) 
(2)) 

is indented correctly; this is how the indentation initially reads. If 
(z) had been do, it would have put the do where the (z) is: 

(loop when x 
do (y) 
do (z)) 



But pressing TfiB reindents it correctly: 

(loop when x 
do (y) 
do (z)) 

The converse can come up, for example: 

(loop with x 
do (z)) 

is fixed with TAB: 

(loop with x 
do (z)) 

(loop with x 
= (z)) 

is indented incorrectly until you press TAB, resulting in: 

(loop with x 
= (z)) 



Centering the 
Current Line 

n-S Center Line 

Centers the text of the current line within the line. With an 
argument n, it centers n lines and moves past them. 

Indenting New Line 

The keystroke combination RETURN TAB gets you into the right 
position to start typing the next line of code. LINE is the 
abbreviation for that combination. 

LINE Indent New Line 

If the next two lines are blank, goes to the next line; otherwise, it 
creates a new blank line following the current one. In any case, it 
does a TAB on that blank line. 
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Reindenting Expression 

c-n-Q Indent Sexp 

Corrects the indentation of the expression following point by 
adjusting the amount of space before each line in the expression. 
c-n-Q positions point in front of the incorrectly indented expression. 
This does not affect the indentation of the current line, but only 
fixes the indentation of following lines with respect to the current 
line. Use after modifying an expression. 

With a numeric argument of n, it fixes the indentation of the next 
n expressions. 

Indenting Region 

c-n-\ Indent Region 

Indents each line in the region. With no argument, it calls the 
current Tab command to indent. With an argument of n, it 
indents each line n spaces in the current font. 

Going Back to 

First Indented Character 

n-M Back To Indentation 

c-m-M 

n-RETURN 

c-n-RETURN 

Positions point before the first nonblank character on the current 
line. 

Indenting Region Uniformly 

c-x TRB Indent Rigidly 

c-X c-I 

Shifts text in the region sideways as a unit. All lines in the region 
have their indentation increased by the numeric argument of the 
command (the argument can be negative). 

Aligning Indentation 

Indent Under (c-n-x) 

Fixes indentation to align under stringy which you click on with the 
mouse cursor or which you specify in the minibuffer. 

When you use the mouse to specify the alignment string, begin by 
putting the cursor on the line you want to indent, then click right, 
click on Indent Under, then either point the cursor (a down-arrow 
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pointing at a box) at a character that you want to line up with and 
click left, or type in a string for which it searches. 

When you type the alignment string in the minibuffer, it searches 
back, line by line, forward in each line, for a string that matches 
the one read and that is farther to the right than the cursor 
already is. It indents to align with the string found, removing any 
previous indentation first. 

Deleting Indentation 

n-* Delete Indentation 

Deletes the newline character and any indentation at the beginning 
of the current line. It tacks the current line onto the end of the 
previous line, leaving one space between them when appropriate, for 
example, at the beginning of a sentence. 

With any numeric argument, it moves down a line first, thus killing 
the end of the current line. 

New Line with 
This Indentation 

n-0 This Indentation 

Makes a new line after the current one, deducing the new line's 
indentation from point's position on the current line. If point is to 
the left of the first nonblank character on the current line, it 
indents the new line exactly like the current one. But if point is to 
the right of the first nonblank character, it indents the new line to 
the current position of point. Regardless, it leaves point at the end 
of the newly created line. 

With a numeric argument, the new line is always indented like the 
current one, no matter where point is. With an argument of zero, 
it indents current line to point. 

Moving Rest of 
Line Down 

c-n-0 Split Line 

Moves rest of current line down one line. It inserts a carriage 
return and indents new line directly beneath point. With a 
numeric argument n> it moves down n lines. 
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Inserting Blank Line 

c-0 Make Room 

Inserts a blank line after point. With a numeric argument n, it 
inserts n blank lines. 

Deleting Blank Line 

c-x c-0 Delete Blank Lines 

Deletes any blank lines around the end of the current line. 
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11. Editing Lisp Programs in Zmacs 
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Lisp Machine programmers develop programs in repeated cycles, 
each a sequence of editing, compiling, testing, and debugging. 
These cycles are often nested. Zmacs allows you to edit and test 
large programs dynamically, without frequent file system operations. 
This manual does not describe any style of interacting with the 
environment in developing Lisp programs. See the section 
"Programming Development Tools and Techniques". It focuses on 
the interaction between programmers and the Lisp Machine, 
presenting ways of using helpful Lisp Machine features and tools 
during each stage of program development. 

As a programmer on a Lisp Machine you typically read a file 
containing Lisp code into an editor buffer, make modifications, test 
the results, make more changes, and so on, until satisfied with the 
behavior of the program. Only then do you need to write the 
buffer back out to the file system. The debugging loop is much 
tighter and more responsive than in traditional programming 
environments. You can even evaluate Lisp forms directly from 
inside the editor, without returning to a Lisp Listener. 
Alternatively, you can divide the screen into a Lisp Listener window 
and a Zmacs window, so that you can direct your attention to 
either without changing the display. 

Zmacs provides extensive features for locating source code of 
specified functions. If an error occurs, the Debugger can cause 
Zmacs to read in the source of the function that got the error. 
You can then debug and recompile the function. Similar features 
complement the message-passing capabilities of the Zetalisp 
language. 

When you edit a file with a Lisp type, Zmacs puts that buffer into 
Lisp mode. A command exists for explicitly placing a buffer in Lisp 
mode: 

Lisp Mode (n-X) Lisp Mode 

Places the current buffer into Lisp mode. 



Base and Syntax Default Settings for Lisp 

When you read a file that has a Lisp file type into the buffer, if 
that file does not begin with an attribute line containing Base and 
Syntax attributes, Zmacs warns that the file "has neither a Base 
nor a Syntax attribute" and announces that it will use the defaults, 
Base 10 and Zetalisp. See the section "Buffer and File Attributes". 
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Overview 

Zmacs differentiates between the different comment indicators for 
different major modes. Comments in Lisp begin with a semicolon. 
The Lisp reader ignores everything between a (significant) semicolon 
and the next newline. By convention, there are three kinds of 
comments, beginning with one, two, and three semicolons: 

• Comments beginning with a single semicolon are placed to the 
right of a line of code, start in a preset column (the comment 
column), and describe what is going on in that line. 

• A comment with two semicolons is a long comment about code 
within a Lisp expression and has the same indentation as the 
code to which it refers. It describes the function of a group of 
lines. 

• A comment headed by three semicolons is normally placed against 
the left margin, and describes a large piece of code, such as a 
function or group of functions. 

This section outlines Lisp commenting conventions and explains 
Zmacs commands for manipulating comments. 

Indenting for Comment 

c-j Indent For Comment 

n-j 

If the current line has no comment, moves point out to the 
comment column (inserting spaces to get there, if necessary) and 
starts a comment by inserting a semicolon there. If the current 
line already has a comment, it indents it correctly and leaves point 
at the beginning of it. Zmacs positions the various kinds of 
comments appropriately. If a comment begins at the left margin, it 
leaves it there. 

With a numeric argument n, it realigns any comments on the next 
n lines, including the current line, but does not create any new 
comments. 

If a comment cannot be positioned at the comment column because 
the associated line of code is too long, comments are moved to the 
right until they are clearly separated from the code. 

Killing a Comment 

c-n-j Kill Comment 

If the current line has a comment, deletes it. 
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Moving Down to 
Comment on Next Line 

n-N Down Comment Line 

Moves point to the beginning of the comment on the next line. If 
there is no comment on the next line, it creates one. If the 
comment on the current line is empty, it deletes it before going to 
the next line. 

With a numeric argument n, it moves point to the beginning of the 
comment on the nth line after the current one. 

Moving up to 
Comment on 
Previous Line 

n-P Up Comment Line 

Moves point to the beginning of the comment on the previous line. 
If there is no comment on the previous line, it creates one. If the 
comment on the current line is empty, it deletes it before going on 
to the previous line. 

With a numeric argument n> it moves point to the beginning of the 
comment on the nth line before the current one. 

Setting the 
Comment Column 

c-X j Set Comment Column 

Sets the comment column to be the current horizontal position of 
the cursor. 

With a numeric argument, it finds the nearest comment above the 
current line, sets the comment column to line up with that 
comment, and actually puts a comment on the current line at that 
column. 

Creating a New 
Indented 
Comment Line 

m-LlNE Indent New Comment Line 

Makes a new blank line after the current line and starts a new 
comment there, indented properly. If there was already a comment 
on the current line, the comment on the new line is of the same 
kind. (That is, it has the same number of semicolons and is 
indented the same.) If there was no comment on the starting line, 
n-LlNE starts a new line, indenting the new line as appropriate for 
the major mode. 
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Inserting and 
Removing Lisp 
Comments From Regions 

c-X c-j Comment Out Region 

Comments out each line in the region. When the region ends at 
the beginning of a line, it does not comment out that line. If any 
part of the line is part of the region, then it does comment out 
that line. 

A numeric argument activates lines in the region that have been 
commented out. When any part of the line is part of the region, it 
removes commenting from around that line. This assumes that 
any comment starting in column 1 is fair game. It stops when it 
encounters a line that does not begin the way a comment would, 
even if more lines that have been commented out remain in the 
region. It does keep the remainder of the region in this case, so 
that you can resume. 

Uncomment Region (n-x) 

Removes all comments from lines whose beginnings are contained in 
the region. 
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Overview 

The commands in this section form a link between the Zmacs 
editor and the Lisp language. They allow the evaluation and 
compilation of code from Zmacs buffers. These commands are an 
important part of the debugging loop. 

When a Lisp form is being compiled or evaluated, the editor displays 
a message that classifies what is being compiled. 

It classifies macros as functions (because these go in the function 
cell of a symbol). For example: 

Compiling Function SUN 
Evaluating Variable MARS 
Compiling Flavor STAR 

Evaluating Lisp Programs 

n-ESCflPE Evaluate Minibuffer 

Evaluates expressions from the minibuffer. You enter Lisp 
expressions in the minibuffer, which are evaluated when you press 
END. The value of the expression itself appears in the echo area. If 
the expression displays any output, that appears as a typeout 
window. 

Evaluate Into Buffer (n-x) 

Evaluates an expression read from the minibuffer and inserts the 
result into the buffer. You enter a Lisp expression in the 
minibuffer, which is evaluated when you press END. The result of 
evaluating the expression appears in the buffer before point. With 
a numeric argument, it also inserts any typeout that occurs during 
the evaluation into the buffer. 

Evaluate Buffer (n-X) 

Evaluates the entire buffer. The result of evaluating the buffer 
appears in the minibuffer. With a numeric argument, it evaluates 
from point to the end of the buffer. 

Evaluate Region (n-x) 
c-sh-E 

Evaluates the region. When no region has been defined, it 
evaluates the current definition. It shows the results in the echo 
area. 

c-n-sh-E Evaluate Region Verbose 

Evaluates the region. When no region has been defined, it 
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evaluates the current definition. It shows the results in a typeout 
window. 

Evaluate Region Hack (n-X) 

Evaluates the region, ensuring that any Lisp variables appearing in 
a defvar have their values set. When no region has been defined, 
it evaluates the current definition. It shows the results in the echo 
area. 

Evaluate Changed Definitions (n-X) 

Evaluates any definitions that have changed in any of the current 
buffers. With a numeric argument, it prompts individually about 
whether to evaluate particular changed definitions (the default 
evaluates all changed definitions). 

Evaluate Changed Definitions of Buffer (n-X) 
n-sh-E 

Evaluates any definitions that have changed in the current buffer. 
With a numeric argument, it prompts individually about whether to 
evaluate particular changed definitions (the default evaluates all 
changed definitions). 

Evaluate And Replace Into Buffer (n-X) 

Evaluates the Lisp object following point in the buffer and replaces 
it with its result. 

c-n-E Evaluate And Exit 

Evaluates the buffer and exits Zmacs. It selects the window from 
which the last ed function or the last debugger c-E command was 
executed. 

Compiling Lisp Programs 

Compile Buffer (n-X) 

Compiles the entire buffer. With a numeric argument, it compiles 
from point to the end of the buffer. (This is useful for resuming 
compilation after a prior Compile Buffer has failed.) 

Compile Changed Definitions (n-X) 

Compiles any definitions that have changed in any of the current 
buffers. With a numeric argument, it prompts individually about 
whether to compile particular changed definitions (the default 
compiles all changed definitions). 
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Compile Changed Definitions of Buffer (n-X) 
n-sh-C 

Compiles any definitions that have changed in the current buffer. 
With a numeric argument, it prompts individually about whether to 
compile particular changed definitions (the default compiles all 
changed definitions). 

Compile File (n-X) 

Compiles a file, offering to save it first (if it has an associated buffer 
that has been modified). It prompts for a file name in the 
minibuffer, using the file associated with the current buffer as the 
default. It does not load the file. 

Load File (n-x) 

Loads a file, possibly saving and compiling it first. It prompts for a 
file name, taking the default from the current buffer. It checks to 
see if the file you are compiling corresponds to a buffer and offers 
to save that buffer if it is modified. If the .bin file is older than . 
the .lisp file, it offers to compile the file first. If the typeout 
window displays any compiler warnings, Load File asks if you really 
want to load the file despite the compiler warnings. 

n-E Compile And Exit 

Compiles the buffer and exits Zmacs. It selects the window from 
which the last ed function or the last debugger c-E command was 
executed. 

Lisp Compiler Warnings 

Compiler warnings are kept in an internal database that you can 
inspect and manipulate in various ways with several editor 
commands. 

Compiler Warnings (n-X) 

Creates the compiler warnings buffer (called *Compiler-Warnings-1*) 
if it does not exist, puts all outstanding compiler warnings in that 
buffer, and switches to that buffer. You can view the compiler 
warnings by scrolling around and doing text searches through them 
using Edit Compiler Warnings (n-X). 

Edit Compiler Warnings (n-X) 

Prompts you with the name of each file mentioned in the database, 
allowing you to edit the warnings for that file. It then splits the 
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Zmacs frame into two windows: the upper window displays a 
warning message and the lower one displays the source code whose 
compilation caused the warning. After you have finished editing 
each function, c-. gets you to the next warning: the top window 
scrolls to show the next warning and the bottom window displays 
the function associated with this warning. Successive c-. s take you 
through all of the warning messages for all of the files you 
specified. When you are done, the last c-. puts the frame back 
into its previous configuration. 

Edit File Warnings (n-X) 

Asks you for the name of the file whose warnings you want to edit. 
You can give either the source file or the compiled file. Only 
warnings for this file are edited. If the database does not have any 
entries for the file you specify, the command prompts you for the 
name of a file that contains the warnings, in case you know that 
the warnings are stored in another file. 

Load Compiler Warnings (n-X) 

Loads a file containing compiler warning messages into the 
warnings database. It prompts for the name of a file that contains 
the printed representation of compiler warnings. It always replaces 
any warnings already in the database. 
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m-< Make () 

Inserts matching parentheses, leaving point between them. With a 
numeric argument n, it encloses the next n Lisp expressions in 
parentheses. When the number of expressions requested cannot be 
satisfied, it beeps and does nothing. With point on the open 
parenthesis of a defun, an argument of 1 encloses the whole defun 
within a new set of parentheses. Any argument larger than 1 
would have no effect. In Text Mode, a word or a phrase within 
parentheses is treated as a Lisp form. 

See also the description of the command n-) : See the section 
"Motion Among Top-level Expressions", page 66. 



179 
March 1985 Zmacs Manual 



Expanding Lisp Expressions 



Two editor commands allow you to expand macros: Macro Expand 
Expression and Macro Expand Expression All. 

c-sh-M Macro Expand Expression 

Reads the Lisp expression following point and expands the form 
itself but not any of the subforms within it. It displays the result 
in the typeout window. With a numeric argument, it pretty-prints 
the result back into the buffer immediately after the expression. 

n-sh-M Macro Expand Expression All 

Reads the Lisp expression following point, and expands all macros 
within it at all levels. It displays the result in the typeout window. 
With a numeric argument, it pretty-prints the result back into the 
buffer immediately after the expression. It assumes that every list 
in the expression is a form, so if car of a list is a symbol with a 
macro definition, the purported macro invocation is expanded. 



180 

Text Editing and Processing March 1985 



Locating Source Code to Edit 



Introduction 

The functions that make up a program or system can depend on 
each other in complicated ways. When you are editing one 
function, you sometimes have to go off and look at another 
function, and possibly modify that one too. 

This section describes the Edit Definition command and other 
commands that list and/or edit various sets of definitions. In 
addition, two pairs of List and Edit commands help identify changed 
code by finding or editing changed definitions in buffers. By 
default, the changed commands find changes made since the file 
was read; use numeric arguments to find definitions that have 
changed since they were last compiled or saved. 

The Zmacs Edit 
Definition Commands 

Edit Definition (n-.) is a powerful command to find and edit 
function definitions, macro definitions, global variable definitions, 
and flavor definitions. In general, Zmacs treats as a definition any 
top-level expression having in functional position a symbol whose 
name begins del 

It is particularly valuable for finding source code, including system 
code, that is stored in a file other than that associated with the 
current buffer. It finds multiple definitions when, for example, a 
symbol is defined as a function, a variable, and another type of 
object. It maintains a list of these definitions in a support buffer. 

m-. Edit Definition 

Edits the newest version of the file that contains the definition of a 
specified Lisp object. It prompts for the name of the definition; if 
one of your buffers already contains the newest version of that 
definition, it selects that buffer. Otherwise, it reads in the source 
file that contains the definition. It always positions the cursor in 
front of the definition. When the object has more than one 
definition, use a numeric argument to m-. to edit another definition 
of the same object. You can repeat this until there are no more 
definitions of that object. 

The prompt has three helpful features: selection by mouse, context 
default, and completion (for definitions already in the buffer). You 
can specify a definition by typing the name into the minibuffer or 
clicking left on a name already in the buffer. If you just press END 
instead of typing a function name, Zmacs assumes that the 
function you want is the one at the front of the innermost 
expression containing point. This default is displayed with the 
prompt. 
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Zmacs finds definitions this way: 

• If the definition is in the current buffer, it moves point there. 

• If the definition is in a different buffer, it changes buffers to get 
to the definition and moves point there. 

• If the definition is in a file that has not been read into a Zmacs 
buffer, Zmacs goes out to the file system to get it, creating a 
new buffer and reading in the file, and then moves point to the 
definition. 

When a symbol has more than one definition (for example, list 
might be defined both as a function and as a global variable), 
Zmacs finds all the definitions, but only presents the first one for 
editing. Zmacs remembers the other definitions, and tells you 
about them with a message in the echo area. When you have 
finished with the first definition, you can look at the next by 
invoking n-. with a numeric argument. Each time you do this, you 
bring up a new definition to be edited, until you run out of 
definitions, n-. displays No more definitions if you try to continue. 

Example of the n-. Command 

Suppose you are modifying a function called sun, which was written 
by someone else, sun calls the unfamiliar luna, and you need to 
find out what luna does before proceeding. Use n-. to peek at the 
definition of luna. 

When you type n-. , Zmacs prompts you for the name of a 
definition. If point is in the expression where luna is called, the 
default name is luna, and you need only press END. If point is 
somewhere else and the default is wrong, you can point at the 
word luna with the mouse or you can type it in. To let you know 
that you can define a name with the mouse, the mouse cursor 
changes to an arrow pointing straight up. All the symbols that are 
names of definitions you could specify become mouse sensitive. 

Edit Installed Definition (n-x) 

Edits the installed version of the file that contains the definition of 
a specified Lisp object. It prompts for the name of the definition; if 
one of your buffers already contains the installed version of that 
definition, it selects that buffer. Otherwise, it reads in the source 
file that contains the definition. It always positions the cursor in 
front of the definition. When the object has more than one 
definition, use a numeric argument to edit another definition of the 
same object. You can repeat this until there are no more 
definitions of that object. 
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Edit Changed Definitions (n-x) 

Determines which definitions in any Lisp Mode buffer have changed 
and selects the first one. It makes an internal list of all the 
definitions that have changed since the buffer was read in and 
selects the first one on the list. Use c-. (Next Possibility) to move 
to subsequent definitions. See the section "Displaying the Next 
Possibility", page 110. 

Edit Changed Definitions accepts a numeric argument to control 
the time point for determining what has changed: 

Value Meaning 

1 For each buffer, since the file was last read (the default). 

2 For each buffer, since the buffer was last saved. 

3 For each definition in each buffer, since the definition was 
last compiled. 



Edit Changed Definitions of Buffer (n-x) 

Determines which definitions in the current buffer have changed 
and selects the first one. It makes an internal list of all the 
definitions that have changed since the buffer was read in and 
selects the first one on the list. Use c-. (Next Possibility) to move 
to subsequent definitions. See the section "Displaying the Next 
Possibility", page 110. 

Edit Changed Definitions of Buffer accepts a numeric argument to 
control the time point for determining what has changed: 

Value Meaning 

1 Since the file was last read (the default). 

2 Since the buffer was last saved. 

3 Since the definition was last compiled. 



The List 

Definition Commands 

List Definitions (n-X) 

Displays the definitions in a specified buffer. It reads the buffer 
name from the minibuffer, using the current buffer as the default. 
It displays the list as a typeout window. The individual definition 
names are mouse sensitive. 
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List Changed Definitions (m-x) 

Displays a list of any definitions that have been edited in any 
buffer. Use c-. (Next Possibility) to start editing the definitions in 
the list. See the section "Displaying the Next Possibility", page 110. 

List Changed Definitions accepts a numeric argument to control the 
time point for determining what has changed: 

Value Meaning 

1 For each buffer, since the file was last read (the default). 

2 For each buffer, since the buffer was last saved. 

3 For each definition in each buffer, since the definition was 
last compiled. 

List Changed Definitions of Buffer (n-X) 

Displays the names of definitions in the buffer that have changed. 
It makes an internal list of the definitions changed since the buffer 
was read in and offers to let you edit them. Use c-. (Next 
Possibility) to move to subsequent definitions. See the section 
"Displaying the Next Possibility", page 110. 

List Changed Definitions of Buffer accepts a numeric argument to 
control the time point for determining what has changed: 

Value Meaning 

1 Since the file was last read (the default). 

2 Since the buffer was last saved. 

3 Since the definition was last compiled. 

The Edit Callers Commands 

When you are modifying a large system, you often have to make 
sure that changing a function does not render unusable other 
functions that call the modified one. Zmacs provides facilities for 
editing the sources of all the functions defined in the current world 
that call a given one. This removes some of the unpleasantness of 
making incompatible changes to large programs and is a good 
example of how Zmacs interacts with the Lisp environment to 
make programming easier. 

Edit Callers (n-x) 

Prepares for editing all functions that call the specified one. The 
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prompt is the same kind that Edit Definition gives you. It reads a 
function name via the mouse or from the minibuffer with 
completion. By default, it searches the current package. You can 
control the package being searched by giving the function an 
argument. With an argument of c-U, it searches all packages; with 
c-u c-U, it prompts for the name of a package to search. It selects 
the first caller; use c-. (Next Possibility) to move to a subsequent 
definition. See the section "Displaying the Next Possibility", page 
110. 

Multiple Edit Callers (n-X) 

Prompts for the names of a group of functions and edits those 
functions in the current package that call any of the specified ones. 
It reads a function name from the minibuffer, with completion, 
initially offering a default function name. It continues prompting 
for more function names until you end the list with RETURN. 

By default, it searches the current package. You can control the 
package being searched by giving the function an argument. With 
an argument of c-u, it searches all packages. With two c-Us, it 
prompts for the name of a package. 

List Callers (n-X) 

Prompts for the name of a function exactly the way Edit Callers 
does, but instead of editing the callers in the current package of the 
specified function, it simply displays their names. The names are 
mouse-sensitive. If you point at one and click left, you can edit the 
source of that caller. If you click right, a menu pops up that offers 
to give the argument list of the selected caller, to disassemble it, to 
edit it, or to see its documentation string. In addition, c-. (Next 
Possibility) works in this context, offering the first caller to be 
edited, and queuing up the other callers to be edited in sequence. 

With an argument of c-U, it lists all the callers in every package. 
With two c-us, it prompts for the name of a package to search. 

Multiple List Callers (n-X) 

Lists all the functions that call the specified functions. It reads a 
function name from the minibuffer, with completion. It continues 
prompting for more function names until you end the list with 

RETURN. 

The list of function names is mouse-sensitive: see List Callers (n-X). 
c-. (Next Possibility) edits the callers. See the section "Displaying 
the Next Possibility", page 110. 
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By default, it searches the current package. You can control the 
package being searched by giving the function an argument. With 
an argument of c-u, it searches all packages. With two c-us, it 
prompts for the name of a package. 
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For complete information about patching: See the section "Patch 
Facility" in Program Development Utilities. 

Making Patches 

During a typical maintenance session you might make several 
changes to existing definitions or write new ones. Rather than 
recompiling the entire system every time you change a source file, 
you can copy only the new or revised code into a patch file and 
write the file ("finish" the patch). Whenever you finish a patch, 
the patch facility automatically compiles the file and records the 
event in a "patch registry" for the system, noting the number of 
the patch, the system being patch, and a brief user-supplied 
description. As soon as a user loads the patch file (after the system 
is loaded), the state of the given system in his or her machine is 
presumably the same as in the developer's machine when the patch 
was finished. 

The patch facility allows you to have several patches in progress at 
once. Thus you can patch several different systems or several 
different minor versions of the same system during one work 
session. The patch facility manages this potentially dangerous 
situation in the following way. Every time you start a patch, a 
number and a place in the patch registry is reserved for the patch 
in production. The patch is marked in-progress. When the patch 
is finished, the entry is completed and the in-progress mark 
removed. If you decide to abort the patch, the registry entry is 
automatically deleted. 

The ability to have more than patch in-progress to more than one 
system makes it imperative that you keep track of the state of your 
various patches. If a patch is left unfinished (unwritten), the 
load-patches function will load neither the in-progress patch or 
any subsequent finished patches. 

The patch facility considers patches to be active or inactive and in 
one of the following states: initial, in-progress, aborted, or finished. 
View Patches (n-x) displays the state of all patches started in this 
work session. If more than one patch is in progress, one of them is 
known as the current patch. The commands that add patches, like 
Add Patch (n-x), add only to the patch considered by the patch 
facility to be the current patch. The command Select Patch (n-x) 
displays a menu of active patches and allows you to make another 
patch the current one. 

In general you should adhere to the following steps in making a 
patch. It is assumed that your system is patchable; that is, the 
:patchable option appears in the system declaration. 
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1. You must load (via make-system) the major version of the 
system that you want to patch. 

2. Read in the source files you want to edit into a Zmacs buffer. 
Make all changes and test them thoroughly. Write the source 
file. 

3. Use the appropriate Zmacs commands to make your patch. 
Begin the patch, using Start Patch (m-X). 

4. Add the changed code to the patch buffer by using Add Patch 
(n-x), Add Patch Changed Definitions of Buffer (n-x), or Add 
Patch Changed Definitions (n-x). 

5. Finish the patch, using Finish Patch (n-x), or abort the patch, 
using Abort Patch (n-x). 

Commands provided for initiating a patch are Start Patch (n-x), 
Start Private Patch (m-x), and Add Patch (n-x). 

Start Patch (n-x) 

Starts a new patch, prompting you for the name of the system to 
be patched; it must be a system currently loaded. It assigns a new 
minor version number for that particular system by writing a new 
version of the patch directory file with an entry for that minor 
version number. The patch is marked as in-progress. It starts 
constructing the patch file in an editor buffer, but does not select 
the buffer. 

While you are making your patch file, the minor version number 
that has been allocated for you is reserved so that nobody else can 
use it. Thus, if two people are patching the same system at the 
same time, they cannot be assigned the same minor version 
number. 

The command does not actually move any definitions into the patch 
file. You must explicitly do so with Add Patch Changed Definitions 
of Buffer (n-X), Add Patch Changed Definitions (n-X), or Add Patch 
(n-X). 

The patch facility permits you to start another patch before 
finishing the current one. However, if your new patch is to the 
same system, the patch facility warns you that you already have a 
patch in progress and allows you to take one of four actions: 

• Abort the in-progress patch and start a new patch. 

• Finish the in-progress patch and start a new patch. 

• Proceed with the second patch (initial patch) for this system and 
leave the in-progress patch intact. 

• Use the existing buffer and do not start a new patch. 
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Start Private Patch (n-X) 

Although similar to Start Patch (m-x), Start Private Patch (n-x) 
does not have any relationship to systems, major and minor version 
numbers, and official patch directories. Rather it allows you to 
make a private patch file that you can load, test, and share with 
other users before you install a numbered patch that is 
automatically available to all users. 

Instead of prompting for a system name, the command prompts for 
a file name. Start Private Patch does not actually move any 
definitions into the patch file. Use Add Patch Changed Definitions 
of Buffer (n-x), Add Patch Changed Definitions (n-x), or Add Patch 
(n-X) to insert the code. Finishing the patch (using Finish Patch 
(n-x)) writes it out to the specified file. 

Note: Use the Load File command or Load File (m-X) to load a 
private patch; the Load Patches command and the load-patches 
function do not load private patches. 

Add Patch (n-x) 

Starts a new patch if none is underway, prompts you for a system 
name, and inserts the region or current definition into the patch 
buffer. If a patch was in progress, Add Patch (n-X) just adds the 
region or current definition to the current patch file. 

If you mistakenly use the command on code that does not work, 
select the buffer containing the patch file and delete it. Then later 
you can use Add Patch (n-X) on the corrected version. For each 
patch you add, it queries for a patch comment, which it then 
inserts in the patch file. Just pressing END means "no comment". 

Add Patch (n-X), Add Patch Changed Definitions (n-X), or Add 
Patch Changed Definitions of Buffer (n-X) insert code into the 
patch file. These commands add only to the current patch buffer 
and warn you if you try to add code from one system to a patch for 
another. 

Add Patch Changed 

Definitions of Buffer (n-X) 

Add Patch Changed Definitions of Buffer (n-x) selects each 
definition that was changed in the buffer and asks you whether or 
not you want the definition patched. 

For each definition, you can respond as follows: 

Response Action 

Y Patches the definition. 
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N Skips the definition. 

P Patches the definition and any additional modified 

definitions in the same buffer without asking any 
more questions. 

A definition needs to be patched if it has been changed since it was 
last patched or if it has not been patched since the file was read 
into the buffer. 

For each patch you add, it queries for a patch comment, which it 
then inserts in the patch file. Just pressing END means "no 
comment". 

Add Patch Changed 

Definitions (n-X) 

Add Patch Changed Definitions (n-x) selects a buffer in which 
definitions were changed and asks whether or not you want to 
patch the changed definitions. Answering N skips the buffer and 
proceeds to the next buffer, if any. Answering Y selects each 
definition that has changed in that buffer and asks you whether or 
not you want the definition patched. For each definition, you can 
respond as follows: 

Response Action 

Y Patches the definition. 

N Skips the definition. 

P Patches the definition and any additional modified 

definitions in the same buffer without asking any 
more questions; when done, it proceeds to the next 
buffer. 

If there are more buffers containing definitions to be patched, it 
asks questions again when it gets to the next buffer. 

A definition needs to be patched if it has been changed since it was 
last patched or if it has not been patched since the file was read 
into the buffer. 

For each patch you add, it queries for a patch comment, which it 
then inserts in the patch file. Just pressing END means "no 
comment". 

When making multiple patches during one work session use the 
Select Patch and View Patches commands to keep track of patches. 
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Select Patch (n-x) 

When you are making more than one patch during a work session, 
Select Patch (n-x) allows you to choose a different patch as the 
current patch from a menu of active patches. The patching 
commands (like Add Patch and Add Patch Changed Definitions of 
Buffer) insert definitions into the patch file that you have selected 
as the current patch. To insert patch definitions into another 
buffer, use Select Patch to choose that buffer as the current patch. 

View Patches (n-x) 

View Patches (n-x) displays the state of all patches started in this 
session. Patches are either active or inactive and can be in one of 
the following states: initial, in-progress, aborted, or finished. 
Inactive patches are in an aborted or finished state. Active 
patches are in an initial or in-progress state. Initial means that 
the patch buffer has been initialized but as yet no definitions have 
been added to the buffer. In-progress means that the patch buffer 
has been initialized and definitions have been added to the buffer. 

View Patches groups the active and inactive patches and identifies 
the current patch. 

After making and testing all of your patches, use the Finish Patch 
command to install the patch in the system. 

Finish Patch (n-x) 

Finish Patch (n-X) installs the patch file so that other users can 
load it. This command saves and compiles the patch file (patches 
are always compiled). If the compilation produces compiler 
warnings, the command asks whether or not you want to finish the 
patch anyway. If you do, or if no warnings are produced, a new 
version of the patch directory file is written. The in-progress mark 
is removed from the entry in the patch registry. 

The command allows you to edit the patch comments, which are 
written to the patch directory file. (load-patches and 
print-system-modifications print these comments.) It then asks 
you whether you want to send mail about the patch. If you say 
"yes", it opens a mail buffer and inserts initial contents, including 
the name of the patch file and your patch comment. 

Note: By default the Finish Patch command queries you about 
sending mail. You can alter this behavior by changing the value of 
the variable zwei:*send-mail-about-patch*. Its valid values are 
:ask, the default value, which queries the user; t, which opens a 
Zmacs mail buffer without querying; and nil, which takes no action 
regarding the sending of patch mail. 
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Sometimes you start making a patch file and for a variety of 
reasons do not finish it — for example, you decide to abort the 
patch, you need to end' your work session at this machine, or your 
machine crashes. In each of these situations it is of the utmost 
importance that you leave the patch directory file in a clean state; 
that is, either go back and finish the patch (as soon as possible!) or 
deallocate the patch number reserved to you. Failure to do so has 
unfortunate consequences: users at your site will not be able to 
load patches. 

In your machine has crashed, use Resume Patch (n-x) to reclaim 
access to the patch number previously assigned to you. You can 
continue with the patch (assuming you saved the source files just 
prior to the crash) or use Abort Patch (n-X) to deallocate the patch 
number. Begin the patch again if you wish. If you simply decide 
to abandon the patch file, then just use Abort Patch. If you must 
boot your machine before finishing the patch, then save the patch 
buffer and as soon as possible use Resume Patch to read in the 
relevant patch file; finish the patch or abort it, as you wish. 

Abort Patch (n-X) 

Abort Patch (m-X) deallocates the minor version number that was 
assigned by the Start Patch or Add Patch commands. It tells 
Zmacs that you are no longer interested in making the current 
patch and offers to kill the patch buffer. The next time you do 
Add Patch (n-X), Zmacs starts a new patch instead of appending to 
the one in progress. 

Resume Patch (n-x) 

Resume Patch (n-x) allows you to return to a patch that you were 
not able to finish in the same boot session in which you started it; 
for example, your machine might have crashed or you had to boot 
your machine suddenly. It reads in the relevant patch file if it was 
previously saved; otherwise it just reclaims your access to the minor 
version number allocated to you when you started the patch. Abort 
or finish the patch. 

Under certain circumstances you might find it necessary to 
recompile and reload a patch file. 
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Recompile Patch (n-x) 

Recompile Patch (n-x) recompiles an existing patch file. This 
command is useful when, for example, an existing patch needs to 
be edited or a compiled patch file becomes damaged in some way. 
Never recompile a patch manually or in any other way except by 
using the Recompile Patch command. This command ensures that 
source and object files are stored where the patch system can find 
them. 

Use Recompile Patch with caution! Recompiling a patch that has 
already been loaded by other users can cause divergent world loads. 

Reload Patch (n-x) 

Reload Patch (n-x) reloads an existing patch file. This command 
makes it easy to reload a patch file without having to know its 
pathname. 

You might want to have your herald announce private patches that 
you make, note-private-patch adds a private patch to the 
database in your world and includes the name of the patch in the 
herald. 



note-private-patch string Function 

Adds a private patch to the database in your world. 
note-private-patch takes a string argument. For example, 
the following adds the private patch called patch.lisp: 

( note-private-patch "s : >smi 1 ler>patch . 1 isp" ) 

Subsequent displays of your herald show the inclusion of 
that patch in your world. 

You create private patches using the Start Private Patch 
(n-x) command and then the standard patch commands for 
adding to and finishing the patch. Use the Load File 
command or Load File (n-x) to load a private patch; the load 
patches command and the load-patches function do not 
load private patches. 
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Overview 



Introduction 



Now that you are familiar with the basic Zmacs concepts and 
techniques, you can set up a large set of minor modes, Zmacs and 
Lisp variables, and parameters to change the way the editor works. 
Zmacs's flexibility allows you to change which keys are connected to 
which commands, write your own commands, and install them in 
lieu of the standard system commands. A few users make 
extremely radical changes to the point where almost every key has 
a new meaning. 

This section describes: 



• Zmacs minor and major modes, and how they provide a degree of 
customization 

• Creating new commands with keyboard macros 

• Setting key bindings 

• Specifying Zmacs variable settings 

• Sample init file forms for automatically reloading your customized 
environment 



March 1985 



195 
Zmacs Manual 



Built-in Customization Using Zmacs Minor Modes 



Definition of 
Minor Modes 

A minor mode: 

• Is an option. 

• Is independent of other minor modes and of the selected major 
mode. 



How It Works 



Zmacs has an extended command for each minor mode (n-X) that 
turns the mode on or off. With no argument, the command turns 
the mode on if it was off and off if it was on. This is known as 
toggling. A positive argument always turns the mode on, and a 
zero argument or a negative argument always turns it off. 

All the minor mode commands are suitable for connecting to 
single- or double-character commands if you want to enter and exit 
a minor mode frequently. See the section "Zmacs Key Bindings", 
page 208. 

For information about setting minor modes permanently: See the 
section "Setting Mode Hooks in Init Files", page 214. 



Example 



Auto Fill Mode (m-X) 

Turns on Auto Fill Mode, a minor mode that inserts Return 
characters automatically to break lines as you type. You can turn 
Auto Fill Mode on regardless of your major mode. If the mode line 
displays Fill, Auto Fill Mode is on. If Auto Fill Mode is already 
turned on, this command turns it off. 

This mode is useful when you are typing large amounts of text. It 
makes it unnecessary to look at the screen or to worry about line 
length: you just type in the text without newlines and Zmacs 
inserts them whenever they are needed. 

Auto Fill Mode works by establishing a hook that runs after you 
press one of the activation characters (SPACE, RETURN, .,?,!, or ]) 
that activate filling in this mode. When you press one of these 
characters in Auto Fill Mode, Zmacs does more than simply insert 
it. First it checks to see whether the line exceeds the maximum 
allowable line length or fill column (see Set Fill Column below). If 
the line is too long, Zmacs finds the last word on the current line 
that fits inside the fill column. Zmacs then inserts a newline right 
after that word. Extra spaces (if any) are deleted from the 
beginning of the newly formed line. 

Because of the way Auto Fill Mode works, you will often find 
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yourself typing a word out beyond the fill column. The word will 
be moved to the next line as soon as you press one of the activation 
characters. 

The fill column is used by Auto Fill Mode (and by the paragraph 
adjusting commands) to decide where to break lines. It is measured 
in pixels, not in characters, so that Auto Fill Mode works even if 
characters of different widths appear in a buffer. (A pixel is a tiny 
rectangular area on the screen that is either all white or all black. 
Pixels are the smallest addressable region of the display. If you 
look closely, you can see the separate rectangular pixels that make 
up everything on the display.) 

You can change the fill column with the following command: 

c-X F Set Fill Column 

Changes the fill column to match up with the current position of 
the cursor. That means that if point is at the end of a line, filled 
lines will not be longer than the current one from now on. 

With a positive numeric argument n less than 200, the fill column 
is set to be n character-widths, and if n is 200 or greater, the fill 
column is set to be n pixels. 



Summary of 
Minor Modes 



Atom Word Mode (n-x) 

Makes word-moving commands, in Lisp mode, move over Lisp 
objects (other than lists and nil instead of words. This command 
does not display anything in the mode line. 

Auto Fill Lisp Comments Mode (c-m-x) 

Turns on auto filling of comments, but not code. This command 
displays Fill -Comments in the mode line. 

Auto Fill Mode (n-X) 

Turns on auto filling. Auto Fill mode allows you to type text 
endlessly without worrying about the width of your screen. Return 
characters are inserted where needed to prevent lines from 
becoming too long. This command displays Fill in the mode line. 

Electric Font Lock Mode (n-x) 

Puts comments in font B. This command displays 
Electric Font- lock in the mode line. 
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Electric Shift Lock Mode (n-X) 

Facilitates typing in programs that are in uppercase. Whenever you 
type a character that is part of a Lisp symbol, such as the name of 
a function, variable, or special form, Zmacs inserts it in uppercase, 
but when you type a character that is part of a character string or 
a comment or after a slash, Zmacs inserts it normally. This 
command displays Electric Shi ft- lock in the mode line. 

EMACS Mode (n-X) 

Provides commands for EMACS users. It puts bit-prefix commands 
on ESCAPE, c-*, and c-c, and Universal argument on c-u. It also 
makes c-l a synonym for TAB, c-H a synonym for BACKSPACE, and 
c-] a synonym for ABORT. This command displays EMACS in the 
mode line. 

Overwrite Mode (n-X) 

Turns on overwrite mode. In overwrite mode, ordinary printing 
characters replace existing text, instead of inserting themselves next 
to it. It is good for editing pictures. This command displays 
Overwrite in the mode line. 

Word Abbrev Mode (n-X) 

Allows you to define word abbreviations that expand as you type 
them. This command displays Abbrev in the mode line. 
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User-defined 
Major Modes 

In Zmacs, you can define your own major modes (see 
zwei:defmajor in the code). 

File Types and 
Major Modes 

You can control the default major mode associated with a particular 
file type. For example, Zmacs sets the major mode to Lisp for files 
with type lisp. The repository for this information is a list called 
fs:*file-type-mode-alist*. 

For example, suppose you wanted to associate the file type tex with 
text mode: 

(push '("tex" . :text) fs:*file-type-mode-alist*) 

The car of an element should be either a canonical type symbol or 
a string when the type is not one of the known canonical types. 

In addition, suppose you have files that would require Scribe mode, 
if Zmacs had such a thing. You can define a correspondence 
between two major modes, using a global variable called 
zwei:*major-mode-translations*. It is an alist of major mode 
names, expressed as keyword symbols. 

Example: 

(push *(:scribe . :text) zwei:*major-mode- translations*) 
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Definition 



How It Works 



A keyboard macro is a command that you define to abbreviate a 
sequence of other commands. If you discover that you are about to 
type c-N c-D 40 times, you can define a keyboard macro to do c-N 
c-D and call it with a repeat count of 40. 



You define a keyboard macro by telling Zmacs that you are about to 
write a macro and then typing the commands that are the 
definition. That is, as you are defining a keyboard macro, the 
definition is being executed for the first time. When you are 
finished, the keyboard macro is defined and also has been, in effect, 
executed once. You can then do the whole thing over again by 
invoking the macro. 



Procedure 



1. To start defining a keyboard macro, type c-x ( 

(Start Kbd Macro). From then on, your commands continue to 
be executed, but also become part of the definition of the macro. 
Macro- level: 1 appears in the mode line. 

2. If you want to perform an operation on each line, do one of the 
following: 

• Start by positioning point on the line above the first one to be 
processed and then begin the macro definition with a c-N 

• Start on the proper line and end with a c-N. 

Either way, repeating the macro operates on successive lines. 

3. After defining the body of the macro, you can terminate it in 
several ways. 

• c-X ) (End Kbd Macro) terminates the definition. 

• An argument of zero to c-X ) automatically repeats the macro 
(upon termination of the definition) until it gets an error or 
reaches the end of the buffer. 

• c-X ) can be given a repeat count as a numeric argument, in 
which case it repeats the macro that many times right after 
defining it, but defining the macro counts as the first 
repetition (since it is executed as you define it). (Subsequent 
invocations ignore the numeric argument contained in the 
macro.) 

Inserting an argument of 5 before ending the macro (. . .c-5 c-x ) ) 
executes the macro immediately four additional times. 
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Starting a 
Keyboard Macro 

c-X ( Start Kbd Macro 

Begins defining a keyboard macro. A numeric argument means 
append to the previous keyboard macro. 

Ending a 
Keyboard Macro 

c-X ) End Kbd Macro 

Terminates the definition of a keyboard macro. 

Viewing a 
Keyboard Macro 

To see the keyboard macro, use View Kbd Macro (m-x), which 
prints the macro at the top of your screen. 

View Kbd Macro (rc-x) 

Displays the specified keyboard macro. The name of the macro is 
read from the minibuffer; just RETURN means the last one defined, 
which can also be temporary. 

Calling the Last 
Keyboard Macro 

The macro thus defined can be invoked again with c-X E (Call Last 
Kbd Macro), which can be given a repeat count as a numeric 
argument to execute the macro many times. 

c-X E Call Last Kbd Macro 

Repeats the last keyboard macro. 



Example 



The example below defines a keyboard macro that goes to the 
beginning of a line, inserts a semicolon, and goes to the next line. 
It also executes the macro four times, including once as it is being 
defined. 

c-X ( 

c-A 

> 

c-N 

c-4 c-X ) 
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For information about setting key bindings permanently: See the 
section "Zmacs Key Bindings", page 208. 

Writing and 

Saving Keyboard Macros 

Writing and saving keyboard macros entails: 

• Defining the macro with zwei:define-keyboard-macro. 

• Installing the macro on a keystroke with 
zwei:make-macro-command. 

• Storing the macro into a comtab with zwei: command-store. 

zwei:define-keyboard-macro takes as its arguments the name of 
the macro and the keystrokes specifying what you want it to do. 

Optionally, you can install the macro on a keystroke with 
zwei:make-macro-command, giving the name of the macro, 
which returns a Lisp function. 

zwei:command-store takes that Lisp function and stores it into a 
comtab, similar to what zwei:set-comtab does. 
zwei:command-store, given the key you want to install the macro 
on and the comtab in which to put it, stores the command in the 
slot of the comtab that you specify. The combination of 
zwei:make-macro-command and zwei:command-store does the 
same thing as the Install Macro (n-x) command. 

Using variations of the following forms you can save the macros on 
disk and, if you wish, edit them. 



Example 1 



Suppose you want to have a command that exchanges the first two 
words on a line. Put this form in your init file: 

(ZWEI:DEFINE-KEYBOARD-MACRO EXCH-FIRST-TWO-WORDS (NIL) 
#\C-A #\M-F #\M-T) 

The macro cannot be more than 255 keystrokes long. If your 
macro gets this long you should be writing in Lisp, since keyboard 
macros are not intended to be a programming language. If 
necessary, you can get around this restriction by breaking your 
macro into parts and having them call each other. 

Suppose you want to install the EXCH-FIRST-TWO-WORDS macro 
on the keystroke s-Q. Put this form in your init file: 
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(ZWEI: COMMAND-STORE (ZWEI: MAKE-MACRO-COMMAND » :EXCH-FIRST-TWO-WORDS) 
#\S-Q ZWEI:*ZMACS-COMTAB*) 



Example 2 

The following form defines a keyboard macro called replace- test, 
which replaces the string dog with the string river: 

(ZWEI:DEFINE-KEYBOARD-MACRO REPLACE-TEST (NIL) 
#\C-S "dog" #\ESCAPE #\M-RUBOUT "river") 

To save the keyboard macro replace- test on the keystroke h-S: 

(ZWEI: COMMAND-STORE (ZWEI: MAKE-MACRO-COMMAND ': REPLACE-TEST) 
#\H-S ZWEI:*ZMACS-COMTAB«) 

The h-S command takes a numeric argument as a repeat count. 

Defining an 
Interactive 
Keyboard Macro 

Within the keyboard macro definition, you can specify steps at 
which you want the macro to query. To define an interactive 
keyboard macro, use the Kbd Macro Query command after 
beginning the macro definition (with Start Kbd Macro). Invoke 
Kbd Macro Query at each spot in the macro where you want the 
macro to query. Then close the definition with End Kbd Macro. 



c-x Q Kbd Macro Query 

Allows user interaction on each iteration of macro, similar to Query 
Replace (n-x). While defining a keyboard macro, press c-x Q at 
each step where you want a pause to occur. Upon execution of the 
macro, it stops and waits at each of those steps for one of the 
following characters: 



SPACE 
RUBOUT 

? or HELP 



c-R 



Continues execution of the macro. 

Skips rest of keyboard macro (use nested c-x ( 
and c-x ) for grouping to control range of skip). 

Displays HELP information. 

Continues but does not iterate anymore. 

Continues, iterates, but does not ask anymore. 

Enters editing mode; c-n-FUNCTlON R resumes 
the keyboard macro. 
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Naming a 
Keyboard Macro 

Having defined a keyboard macro, you can name it with Name Last 
Kbd Macro (n-X). A prompt (Name for macro:) appears in the 
minibuffer. 

Name Last Kbd Macro (m-X) 

Assigns a name to the most recent temporary keyboard macro, 
making it permanent. The new name for the macro is read from 
the minibuffer. 

Using Keyboard 
Macros to Sort 

You can use a keyboard macro to set up a sorting mechanism and 
run it on any region of text. 

For information about how to sort using keyboard macros, see the 
description of Sort Via Keyboard Macros (n-x): See the section 
"Overview of Sorting in Zmacs", page 112. 

Installing a Macro 
on a Key 

To bind the macro to the key of your choice, use Install Macro 
(n-X). You are asked to identify the macro and specify the key(s) 
to which you want it bound. 

Install Macro (n-X) 

Installs a specified user macro on a specified key. The name of the 
macro is read from the minibuffer, and the keystroke on which to 
install it is read in the echo area. If the key is currently holding a 
command prefix (such as c-X), it asks you for another character, so 
that you can redefine c-X commands. However, with a numeric 
argument, it assumes you want to redefine c-x itself, and does not 
ask for another character. 

Installing a Mouse Macro 

You can bind the macro to a mouse click instead of a key using 
Install Mouse Macro (n-X). This command works similarly to 
Install Macro. 

Install Mouse Macro (n-x) 

Installs a specified user macro on a specified mouse click. The 
name of the macro is read from the minibuffer, and the mouse 
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click on which to install it is read in the echo area. When the 
mouse is clicked to invoke this macro, the macro is invoked from 
the current location of the mouse cursor. 

Deinstalling a Macro 

To remove the macro from that key, use Deinstall Macro (n-x). 
The key is rebound to the standard system usage, if any. 

Deinstall Macro (m-x) 
Deinstalls a keyboard macro. 



Example 



This example shows how to install a macro and deinstall the same 
macro: 

you type: n-X Install Macro 

minibuffer: Name of macro to install (CR for last macro defined) 

you type: nacro-nane or CR 

minibuffer: Key to get it: 

you type: h-T 

A menu appears and asks you in which comtab to install the macro: 

• Just this editor 

• Zmacs 

• Zwei 

Click on your choice. 

minibuffer: Command #<DTP-CLOSURE 34465726> installed on Hyper-T. 

you type: n-X Deinstall Macro 
minibuffer: Key to deinstall: 
you type: h-T 

The menu appears and asks you to specify in which of the three 
comtabs to deinstall the macro. Click on your choice. 

minibuffer: Command NIL installed on Hyper-T. 

For information about saving keyboard macros permanently: See 
the section "Zmacs Key Bindings", page 208. 
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Making Tables 

Using Keyboard Macros 

The keyboard macro facility implemented with the c-n-FUNCTiON 
key provides more features, such as an easy way to make tables. 

c-n-FUNCTION 

Reads a keyboard macro command, consisting of an optional 
numeric argument made up of any number of digits (0-9) followed 
by a non-numeric character, usually a letter. Each keyboard macro 
command must be preceded by the c-n-FUNCTiON prefix. After 
typing the prefix, you may type HELP for a list of available keyboard 
macro commands. 

Keyboard Macro Commands for c-n-FUNCTiON 

9-9 Optional numeric argument. 

c Calls a macro by name. Prompts in the minibuffer for the 

name of the macro. 

P Begins a macro definition (same as c-x ( — See the section 

"Starting a Keyboard Macro", page 200.) 

R Ends a macro definition (same as c-X ) — See the section 

"Ending a Keyboard Macro", page 200.) 

M Defines a named macro. Prompts for the name of the 

macro to define and then enters macro definition mode. 

s Stops (aborts) macro definition (also c-G). 

D Defines a named macro but does not execute it while 

reading its characters. 

SPACE Inserts pauses for user interaction in the macro (same as 
c-X Q — See the section "Defining an Interactive Keyboard 
Macro", page 202.) 

fl Steps though characters on successive iterations (for 

example, letters and numbers). Asks for starting character, 
amount to increase (or decrease if negative) on each 
iteration. 

u Allows typein terminated by c-m-FUNCTlON R. This allows 

you to stop while in the middle of defining the macro, do 
other things in the editor, and then go back and finish 
defining the macro. 

T Allows typein every iteration. 

The difference between c-n-FUNCTlON u and c-n-FUNCTION T is that 
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c-m-FUNCTION u allows typein while defining a macro that does not 
get stored in the macro, hence does not executed on subsequent 
iteration nor when the macro is called again, c-m-function T 
allows typein on every iteration. As with c-n-FUNCTlON u, the 
typein while defining the macro does not get stored in the macro. 
But on each subsequent iteration, new typein will be requested. 



Example 1 



The following example shows how to create a macro that constructs 
a table using c-n-FUNCTlON fl. 

you type: c-X ( 

Minibuffer: Macro-level: 1 * 

you type: c-n-FUNCTION fl 

Minibuffer: Initial character (type a, one-character string): 

you type: a RETURN s 

Minibuffer: Amount by which to increase it (type a decimal number) 

you type: 1 RETURN 

(Zmacs inserts the a into the buffer.) 

you type: c-2 c-6 c-X ) 

As you close the macro, Zmacs inserts into the buffer: 
abedefgh i jklmnopqrstuvwxyz 

by executing the macro 26 times, increasing the letter once each 
time. 



Example 2 



The following example shows how to create a macro that constructs 
a table using c-n-FUNCTION fl, and this time, c-n-FUNCTION T, which 
allows typein during every iteration of the macro: 



March 1985 



207 
Text Editing and Processing 



Creating New Commands with Keyboard Macros, cont'd. 



you type 

Mini buffer 
you type 
you type 

Minibuffer 
you type 

Minibuffer 
you type 
you type 
you type 

Minibuffer 
you type 
you type 

Minibuffer 
you type 
you type 
you type 
you type 
you type 
you type 
you type 
you type 
you type 
you type 



c-X ( 

Macro- level: 1 * 

Item SPRCE 

c-n-FUNCTION fl 

Initial character (type a one-character string): 

1 

Amount by which to increase it (type a decimal number) 

1 

TAB 

c-n-FUNCTION T 

Macro- level: 2 * 

Rosemary 

c-n-FUNCTION R 

Macro- level: 1 * 

RETURN 

c-5 c-X ) 

Sage 

c-n-FUNCTION R 

Thyme 

c-n-FUNCTION R 

Parsley 

c-n-FUNCTION R 

Pepper 

c-n-FUNCTION R 



The table looks like this: 



Item 1 


Rosemary 


Item 2 


Sage 


Item 3 


Thyme 


Item 4 


Parsley 


Item 5 


Pepper 
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Key Bindings 



Definition 

A key binding is the set of specific keystrokes that invoke a specific 
command. 

How Key Bindings 
Work: the Comtab 

A command table, or comtab, assigns a command to each possible 
keystroke. While Zmacs is running, there is always a unique 
selected comtab, in which Zmacs finds the command that 
corresponds to each user keystroke. 

When you type a keystroke, Zmacs looks up the keystroke in the 
currently selected comtab, finds the appropriate command, and runs 
it. Usually the command's side effects all occur within the buffer: 
Point might be moved and text might be deleted, inserted, or 
rearranged. Sometimes a command has more extensive side effects. 
A command can alter or replace the selected comtab itself, in which 
case Zmacs looks up the next keystroke in the new command table. 

Zmacs's basic state consists of the standard editor key bindings, 
which reside in one special command table, the standard comtab 
(Zwei comtab). The standard comtab interacts with the Zmacs 
comtab and the various mode-dependent comtabs. The typical 
selected comtab when in Zmacs is "unnamed" for mode-specific key 
bindings, which indirects to "Zmacs", which indirects to "Zwei". 
Although the standard comtab can be temporarily replaced, it is 
always reselected eventually, often after only one "nonstandard" 
keystroke. 

A keystroke that functions as a prefix actually runs a command 
that replaces the standard comtab for one keystroke. This is the 
mechanism by which multikeystroke commands are implemented. 
For example, there are many two-stroke commands whose first 
keystroke is c-x. This keystroke runs a command that brings in 
its own comtab before interpreting the next stroke. 

Setting the Key 

If you want to put a command on the keystroke of your choice, use 
Set Key. This command works for any of the already defined 
commands. 

Set Key (n-x) 

Installs a specified command on a specified key. If the key is 
currently holding a command prefix (such as c-X), it asks you for 
another character so that you can redefine c-X commands. 
However, with a numeric argument, it assumes you want to 
redefine c-x itself and does not ask for another character. 
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It assigns key bindings in the editor that are active in all buffers, 
and takes two arguments: the name of a command, and a 
keystroke to invoke it. It reads the name of the command in the 
minibuffer, completing any command name in any comtab. 

Install Command 

If you want to put a function on the keystroke of your choice, use 
Install Command. It takes a function, regards it as a command, 
and puts it on a key. 

Install Command (n-X) 

Installs a specified function as a command in the comtab, on a 
specified key. It takes two arguments: the name of the function 
(the current definition, that is, top-level expression), and a 
keystroke to invoke it. (Zmacs treats as a definition any top-level 
expression having in functional position a symbol whose name 
begins "def '.) If the key is currently holding a command prefix 
(such as c-X), it asks you for another character so that you can 
redefine c-X commands. However, with a numeric argument, it 
assumes you want to redefine c-X itself and does not ask for 
another character. 
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How to Specify Zmacs Variable Settings 



Definition 

A variable is a name that is associated with a value, for example, a 
number or a string. Zmacs has editor variables that you can set 
for customization. (Variables can also be set automatically by major 
modes.) 

You can distinguish the names of Zmacs variables from other Lisp 
variables by their names — the first letters are capitalized and the 
names contain spaces rather than hyphens. 

Finding Out 

About Zmacs Variables 

To examine the value of a single Zmacs variable, use Describe 
Variable (n-X). To print a complete list of all variables, use List 
Variables (n-x). 

Some commands refer to variables that do not exist in the initial 
environment. Such commands always use a default value if the 
variable does not exist. In these cases you must create the variable 
yourself if you wish to use it to alter the behavior of the command. 

Describing Zmacs Variables 

Describe Variable (n-x) 

Displays the documentation and current value for a single Zmacs 
variable. It reads the variable name from the minibuffer, using 
completion. 

Listing Zmacs Variables 

List Variables (n-x) 

Lists all Zmacs variables and their values. With a numeric 
argument, this command also displays the documentation line for 
the variable. 

Listing Variables 
by Matching a String 

HELP y Variable Apropos 

c-HELP y 
c-n-? V 

Displays the names of all possible Zmacs variables containing a 
specific substring. With a numeric argument, this command also 
displays the documentation lines for the variables. 
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Example 

One example of such a Zmacs variable is the Fill Column variable, 
which specifies the width; in pixels, used in filling text. 

For example, c-1 HELP V prompts in the minibuffer Variable 
Apropos (substring): and you type fill col. It does pattern 
matching on the variable name and thus matches Fill column, 
which displays: Fill column: 576. Width in pixels used in 
filling text. 

Setting Variables 

Settable Zmacs Variables 

You can view all settable Zmacs variables with the List Variables 
command. 

The following are some examples of variables that can be set with 
Set Variable. In addition, they can be set in init files by using the 
internal form of their names. For example, Region Marking Mode 
is zwei:*region-marking-mode* internally. 



Region Marking Mode 

Value: :reverse-video for setting the region to 
reverse video. The default is :underline. 



Region Right Margin Mode 

Value: t. Causes whatever marks the region (reverse 
video or underlining) to extend across unfilled space 
to the right margin. The default is nil. 

One Window Default 

Controls which window remains selected after a One 

Window (c-x l ) command when you were using 

more than one window. Possible values: 

:current 

:other 

:top 

•.bottom 

This feature operates best when the current layout 
has no more than two windows. The value rcurrent 
is the only one that is always well defined with more 
than two windows on the screen. 
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Check Unbalanced Parentheses When Saving 

Controls whether Zmacs checks a file for unbalanced 
parentheses when you are saving the file. The check 
is on (t) by default. When it checks a file that you 
are saving and finds unbalanced parentheses, it 
queries you about whether to go ahead and save 
anyway. This applies to all major modes based on 
Lisp; it is ignored for text modes. 



Set Variable 



Set Variable (n-x) 

Sets any existing Zmacs variable. This command reads the name of 
a variable (with completion), displays its current value and 
documentation, and prompts in the minibuffer for a new value. It 
does some checking to see that the new value has the right type. 

Although either uppercase or lowercase works, you are encouraged 
to capitalize each word of the name for aesthetic reasons, since 
Zmacs stores the name as you give it. 
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Customizing Zmacs in Init Files 



Introduction 

As you gain sophistication with the more advanced features, you 
will find the settings of parameters that most please you and put 
these into a command file (init file) that the system executes every 
time you log in. 

Creating an Init File 

Create a file named lispm-init.lisp (or with the correct Lisp file 
type suffix for your host operating system) in your home directory 
on your host system and put your Zmacs customizations there. 

This section contains examples of forms that you can place inside a 
login-forms in your init file to customize the editor. 

login-forms is a special form for wrapping around a set of forms in 
your init file. It evaluates the forms and arranges for them to be 
undone when you log out. 

Setting Editor Variables 

The forms described show how to set Zmacs variables (the kind 
that Set Variable (n-X) sets). 

To set these variables, which are symbol macros, you must use the 
setf macro. For a description of symbol macros: See the section 
"Symbol Macros" in Reference Guide to Symbolics-Lisp. For a 
description of the setf macro: See the macro setf in Reference 
Guide to Symbolics-Lisp. 

Ordering Buffer Lists 

(SETF ZWEI:*SORT-ZMACS-BUFFER-LIST* NIL) 

This displays the list of buffers in the order the buffers were 
created rather than in the order they were most recently visited. 

Putting Buffers Into 
Current Package 

(SETF ZWEI:*DEFAULT- PACKAGE* NIL) 

This puts buffers created with c-X B (Select Buffer) into whatever 
package is current; the default is to put them in the user package. 



Setting Default 
Major Mode 



(SETF ZWEI:*DEFAULT-MAJOR-MODE* ':TEXT) 

This sets the default major mode to Text Mode for buffers with no 
Mode attribute and no major mode deducible from the file type; the 
default is Fundamental Mode. 
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Setting Find File 

Not to Create New Files 



(SETF ZWEI:*FIND-FILE-NOT-FOUND-IS-AN-ERROR* T) 

This beeps and prints an error message when you give 
c-x c-F (Find File) the name of a nonexistent file. The default 
prints (New File) and creates an empty buffer, which when saved 
by c-X c-S (Save File) creates the file that was nonexistent. 



Setting Goal 
Column for Real 
Line Commands 

(SETF ZWEI:*PERMANENT-REAL-LINE-GOAL-XPOS* 0) 

This moves subsequent c-N and c-P (Down Real Line and Up Real 
Line) commands to the left margin, like doing c-8 c-x c-N (Set 
Goal Column to zero). 

Fixing White Space 

for Kill/Yank Commands 

(SETF ZWEI:*KILL- INTERVAL-SMARTS* T) 

This tells the killing and yanking commands optimize white space 
surrounding the killed or yanked text. 

Setting Mode Hooks 

Each major mode has a mode hook, a variable which, if bound, is a 
function that is called with no arguments when that major mode is 
turned on. 

Electric Shift Lock 
in Lisp Mode 

(SETF ZWEI: LISP-MODE-HOOK 'ZWEI:ELECTRIC-SHIFT-LOCK-IF-APPROPRIATE) 

This tells Lisp major mode to turn on Electric Shift Lock minor 
mode unless the buffer has a Lowercase attribute. The effect is 
that by default Lisp code is written in upper case. 

Auto Fill in Text Mode 

(SETF ZWEI: TEXT-MODE-HOOK 'ZWEI:AUTO-FILL-IF-APPROPRIATE) 

This tells Text major mode to turn on Auto Fill minor mode unless 
the buffer has a Nofill attribute. The effect is that by default lines 
of text are automatically broken by carriage returns when they get 
too wide. 
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Key Bindings 



To bind keys, you first define the comtab in which to put the 
binding. For example; *standard-comtab* and 
♦standard-control-x-comtab* define features of all Zwei-based 
editors; *zmacs-comtab* and *zmacs-control-s-comtab* define 
features that are Zmacs-specific. 



Balanced Quotation 
Marks and Asterisks 



ZWEI: (SET- COMTAB ^STANDARD- COMTAB* 

'(Am-/" COM-MAKE-/(/) 
Ac-m-/" COM-MOVE-OVER/) 
Am-/* COM-MAKE-/(/) 
Ac-m-/* COM-MOVE-OVER-/) 
)) 

This defines commands to insert balanced pairs of quotation marks 
or asterisks into the buffer. For example, you can type an 
asterisked special variable name as m-* F00, which inserts *foo* into 
the buffer, ensuring that one does not forget to type the trailing 
asterisk. 



White Space in Lisp Code 



ZWEI : (SET-COMTAB *STANDARD-CONTROL-X-COMTAB* 

' (ASP COM-CANONICALIZE-WHITESPACE) ) 

This defines c-X SPACE as a command that makes the horizontal 
and vertical white space around point (or around mark if given a 
numeric argument or immediately after a yank command) conform 
to standard style for Lisp code. 



c-m-L on the SQUfiRE Key 



ZWEI: (SET-COMTAB *ZMACS-COMTAB* 

• ( ASQUARE COM-SELECT-PREVIOUS-BUFFER) ) 

This defines the square key to do the same thing as c-n-L. This 
key binding is placed in *zmacs-comtab* rather than 
*standard-comtab* since buffers are a feature of Zmacs, not of all 
Zwei-based editors. 



Edit Buffers on c-X c-B 



ZWEI: (SET-COMTAB *ZMACS-CONTROL-X-COMTAB* 
'(Ac-B COM-EDIT-BUFFERS)) 

This makes c-X c-B invoke Edit Buffers rather than List Buffers. 
This key binding is placed in *zmacs-control-x-comtab* rather 
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than *standard-control-x-comtab* since buffers are a feature of 
Zmacs, not of all Zwei-based editors. 



Edit Buffers on n-x 



M-. 071 V\-(L) 



ZWEI:(SET-COMTAB *ZMACS-COMTAB* 
() 
( MAKE-COMMAND-ALIST » ( COM-EDIT-BUFFERS) ) ) 

This makes Edit Buffers available on n-x in Zmacs (by default it is 
only available on c-n-x). 



ZWEI:(SET-COMTAB *ZMACS-COMTAB* 

' (#\m-MOUSE-L COM-EDIT-DEFINITION) ) 

This makes clicking the left mouse button while holding down the 
METfi key do what n-. does. Invoking this command from the 
mouse is convenient when you specify the name of the definition to 
be edited by pointing at it rather than typing it. 
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Appendix A. Zmacs Help Command Summary 



This section lists the names of the available help commands grouped according to the 
context in which they are available. The purpose of this section is to summarize the 
capabilities and to help you determine both the overall contexts for which you can 
find help and a particular function that might be what you are looking for. 

Zmacs Commands 

for Finding Out 

About the State of Buffers 

Edit Buffers (n-X) 

Edit Changed Definitions (n-x) 

Edit Changed Definitions Of Buffer (n-x) 

List Buffers (c-x c-B) 

List Changed Definitions (n-x) 

List Changed Definitions Of Buffer (n-X) 

List Definitions (n-x) 

List Matching Lines (n-X) 

Print Modifications (n-x) 

Select System as Tag Table (n-X) 

Tags Search (n-X) 

Zmacs Commands 

for Finding Out 

About the State of Zmacs 

Apropos (HELP A, n-X) 

Describe Variable (n-x) 

Edit Zmacs Command (n-x) 

List Commands (n-X) 

List Registers (n-X) 

List Some Word Abbrevs (n-x) 

List Tag Tables (n-X) 

List Variables (n-x) 

List Word Abbrevs (n-X) 



Zmacs Commands 
for Finding Out 
About Lisp 

Brief Documentation (c-sh-D) 
Describe Variable At Point (c-sh-V) 
Edit Callers (n-X) 
Edit Definition (n-.) 
Edit File Warnings (n-x) 
Function Apropos (n-X) 
List Callers (n-x) 
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List Matching Symbols (n-x) 
Long Documentation (n-sh-D) 
Multiple Edit Callers (n-x) 
Multiple List Callers (n-X) 
Quick Arglist (c-sh-fl) 
Where Is Symbol (n-x) 

Zmacs Commands 
for Finding Out 
About Flavors 

Describe Flavor (n-x) 

Edit Combined Methods (n-x) 

Edit Methods (n-x) 

List Combined Methods (n-x) 

List Methods (n-X) 

Zmacs Commands 
for Interacting 
with Lisp 

Break (SUSPEND) 

Compile And Exit (n-2) 

Compile Buffer (n-x) 

Compile Changed Definitions (n-x) 

Compile Changed Definitions Of Buffer (n-sh-c, n-x) 

Compile File (n-x) 

Compile Region (c-sh-c, n-x) 

Compiler Warnings (n-x) 

Edit Compiler Warnings (n-x) 

Evaluate And Exit (c-n-2) 

Evaluate And Replace Into Buffer (n-x) 

Evaluate Buffer (n-x) 

Evaluate Changed Definitions (n-x) 

Evaluate Changed Definitions Of Buffer (n-sh-E, n-x) 

Evaluate Into Buffer (n-x) 

Evaluate Minibuffer (escape) 

Evaluate Region (c-sh-E, n-x) 

Evaluate Region Hack (n-x) 

Evaluate Region Verbose (c-n-sh-E) 

Load Compiler Warnings (n-x) 

Macro Expand Expression (c-sh-M, n-x) 

Trace (n-X) 

Quit (c-Z) 
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13. Font Basic Concepts 



On the Symbolics Lisp Machine, characters can be typed out in any of a number of 
different typefaces. Some text is printed in characters that are small or large, 
boldface or italic, or in different styles altogether. Each such typeface is called a 
font. A font is conceptually an array, indexed by character code, of pictures showing 
how each character should be drawn on the screen. The Font Editor (FED) is a 
program that allows you to create, modify, and extend fonts. 

A font is represented inside the Lisp Machine as a Lisp object. Each font has a 
name. The name of a font is a symbol, usually in the fonts package, and the 
symbol is bound to the font. A typical font name is tr8. In the initial Lisp 
environment, the symbol fonts:tr8 is bound to a font object whose printed 
representation is something like: 

#<font tr8 234712342> 

The initial Lisp environment includes many fonts. Usually there are more fonts 
stored in BFD files in file computers. New fonts can be created, saved in BFD files, 
and loaded into the Lisp environment; they can also simply be created inside the 
environment. 

If you are loading a font contained in a font file in one of the font directories, the 
system loads that font the first time you reference it. However, if you are loading a 
font contained in a file somewhere else in the file system, load that font using the 
function fed:read-font-from-bfd-file pathname, where pathname is the pathname 
of the font file. See the section ":load-bfd Transformation of defsystem" in 
Program Development Utilities. 

The tv package contains the window system, which includes fonts for screen display 
(as opposed to fonts for hardcopying). 



13.1 Attributes of TV Fonts 

Fonts, and characters in fonts, have several interesting attributes. 

Character Height Font Attribute 

One attribute of each font is its character height. This is a nonnegative integer 
used to figure out how tall to make the lines in a window. Each window has a 
certain line height. The line height is computed by examining each font in the font 
map, and finding the one with the largest character height. This largest character 
height is added to the vertical spacing (in pixels) between the text lines (vsp) 
specified for the window, and the sum is the line height of the window. The line 
height, therefore, is recomputed every time the font map is changed or the vsp is 
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set. This ensures that any line has enough room to display the largest character of 
the largest font and still leave the specified vertical spacing between lines. One 
effect of this is that if you have a window that has two fonts, one large and one 
small, and you do output in only the small font, the lines are still spaced far enough 
apart to accommodate characters from the large font. This is because the window 
system cannot predict when you might, in the middle of a line, suddenly switch to 
the large font. 

Baseline Font Attribute 

Another attribute of a font is its baseline. The baseline is a nonnegative integer 
that is the number of raster lines between the top of each character and the base of 
the character. (The base is usually the lowest point in the character, except for 
letters that descend below the baseline, such as lowercase p and g.) This number is 
stored so that when you are using several different fonts side-by-side, they are 
aligned at their bases rather than at their tops or bottoms. So when you output a 
character at a certain cursor position, the window system first examines the baseline 
of the current font, then draws the character in a position adjusted vertically to 
make the bases of the characters all line up. 

Character Width Font Attribute 

The character width can be an attribute either of the font as a whole, or of each 
character separately. If there is a character width for the whole font, it is as if each 
character had that character width separately. The character width is the amount 
by which the cursor position should be moved to the right when a character is 
output on the window. This can be different for different characters if the font is a 
variable-width font, in which a W might be much wider than an i. Note that the 
character width does not necessarily have anything to do with the actual width of 
the bits of the character (although it usually does); it is merely defined to be the 
amount by which the cursor should be moved. 

Left Kern Font Attribute 

The left kern is an attribute of each character separately . Usually it is zero, but it 
can also be a positive or negative integer. When the window system draws a 
character at a given cursor position, and the left kern is nonzero, the character is 
drawn to the left of the cursor position by the amount of the left kern, instead of 
being drawn exactly at the cursor position. In other words, the cursor position is 
adjusted to the left by the amount of the left kern of a character when that 
character is drawn, but only temporarily; the left kern only affects where the single 
character is drawn and does not have any cumulative effect on the cursor position. 

Fixed-width Font Attribute 

A font that does not have separate character widths for each character and does not 
have any nonzero left kerns is called a fixed-width font. The characters are all the 
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same width and so they line up in columns, as in typewritten text. Other fonts are 
called variable-width because different characters have different widths and things do 
not line up in columns. Fixed-width fonts are typically used for programs, where 
columnar indentation is used, while variable-width fonts are typically used for 
English text, because they tend to be easier to read and to take less space on the 
screen. 

Blinker Width and Blinker Height Font Attributes 

The blinker width and blinker height are two nonnegative integers that tell the 
window system an attractive width and height to make a rectangular blinker for 
characters in this font. These attributes are completely independent of all other 
attributes and are only used for making blinkers. Using a fixed width blinker for a 
variable-width font causes problems; the editor actually readjusts its blinker width as 
a function of what character it is on top of, making a wide blinker for wide 
characters and a narrow blinker for narrow characters. The easiest thing to do is to 
use the blinker width as the width of the blinker. This works well with a fixed- 
width font. 

Char-exists Table Font Attribute 

The char-exists table is an art-lb array for each font. It has a 1 for each character 
that actually exists in the font, and a for other characters. This table is not used 
by the character-drawing software; it is for informational purposes. Characters that 
do not exist have pictures with no bits "on" in them, just like the Space character. 
Most fonts implement most of the printing characters in the character set, but some 
are missing some characters. 



13.2 Standard TV Fonts 

You can use Show Font HELP in the Lisp Listener or the List Fonts (n-x) command in 
Zmacs to get a list of all the fonts that are currently loaded into the Lisp 
environment. The fonts package contains the names of all fonts. Here is a list of 
some of the useful fonts: 

fontsicptfont This is the default font, used for almost everything. 

fonts:jessl4 This is the default font in menus. It is a variable- 

width rounded font, slightly larger and more attractive 
than medfnt. 

fontsrcptfonti This is a fixed-width italic font of the same width and 

shape as fonts.-cptfont, the default screen font. It is 
most useful for italicizing running text along with 
fonts:cptfont. 

fontstcptfontcb This is a fixed-width bold font of the same width and 

shape as fontsrcptfont, the default screen font. 
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fonts:medfht 
fontsrmedfhb 

fonts:hll2i 
fontsrtrlOi 
fonts:hllO 
fonts:h!10b 



This is a fixed-width font with characters somewhat 
larger than those of cptfont. 

This is a bold version of medfnt. When you use Split 
Screen, for example, the [Do It] and [Abort] items are 
in this font. 

This is a variable-width italic font. It is useful for italic 
items in menus; Zmail uses it for this in several menus. 

This is a very small italic font. It is the one used by 
the Inspector to say "More above " and "More below ". 

This is a very small font used for nonselected items in 
Choose Variable Values windows. 

This is a bold version of hllO, used for selected items in 
Choose Variable Values windows. 
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14. Entering and Leaving FED 



You can enter FED: 

• By using [Font Edit] in the System menu. 

• By typing the Edit Font command at any Lisp Listener. 

• By typing the fed Lisp form at any Lisp Listener. 

The first time you invoke FED in a session, it takes about 15 seconds to start up; 
after that, entering FED is very quick. When the startup is complete, you see a 
FED Frame, the window configuration used by FED. You are not editing any 
particular font: you can experiment with character drawing in this state, but it is 
best to select a font first. 

If you know which font you wish to edit before entering FED, you can save time 
and steps by typing the font-name as an argument to Edit Font or fed: 

Edit Font font-name 

or 

(fed font-name) 

font-name can be a string, a BFD object, or any atomic symbol (on any package) 
whose print name is the name of the font you wish to edit. 

You can exit FED either by selecting some other activity (via the System menu, 
mouse, the SELECT key, or FUNCTION S), or by using [EXIT] in FED's menu. 
Whenever you reinvoke FED in the same session, you return to the editing that you 
were doing when you left FED. Thus, only one FED exists per session, and you do 
not lose your work by leaving it. 

Should FED become unusable because of an error, you can type the following form 
at a Lisp Listener: 

(fed :reinitialize) 

This creates a completely new FED (although not destroying the old one). 



226 

Text Editing and Processing 



March 1985 




Figure 1. Initial FED Display 
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15. Font Editor Basic Concepts 



15.1 FED, the Subsystem 



FED accepts both menu commands and character (keyboard) commands. 

When you enter FED, you see a complex frame of many panes. The following are 
descriptions of the panes in the FED frame: 



Drawing Pane 



Character Box 



Sample Pane 



The largest pane is the drawing pane, which contains a grid of 
dots forming an array of squares, and a box drawn in the middle. 
When you edit a character, FED draws the character in this pane, 
magnified 12 to 1. (You can choose other magnifications with the 
[Configure] and [Grid Size] FED menu commands.) Each box, 
delineated by four dots, represents one pixel (bit-raster dot) of the 
character being edited. 

The basic technique of editing characters is to draw lines, points, 
and curves on this pane, using the mouse as a graphic input 
device, and thus modify the bit-raster definition of the character 
being edited. Mouse clicks on the drawing pane draw and clear 
points. For information on mouse use on the drawing pane: See 
the section "Drawing in FED", page 235. 

The box drawn in the center of the drawing pane is called the 
character box. It shows the font baseline and character height, as 
well as the width and kerning of the character being edited. The 
box itself shows the right and left margins of the character, and 
the top and baseline of the font. The line under the character 
box shows the character height of the font, which is the height 
that the window system uses to compute line spacing for windows 
with the current font in their font map. It represents, in 
essence, the maximum height of any character in the font, 
although it is a font parameter, not one computed by inspecting 
all characters in a font. 

You can alter the positioning of the character box, as well the 
character width it represents. See the section "Viewing and 
Altering a Character in the FED Character Box", page 237. 

The topmost pane of the FED frame is called the sample pane. 
It shows what the character being edited looks like in normal size. 
That display appears in the leftmost part of the sample pane. 
About an inch to the right of that, the sample pane shows a life- 
size sample string in the font being edited. (You can set this 
sample string with the [Set Sample] FED menu command.) The 
sample string allows you to see what a given word or phrase, 
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drawn in the font being edited, looks like. This allows you to see 
your changes to a given character in context. Note that the 
sample pane changes size as you select fonts of differing character 
height. 

Prompt Pane Between the sample pane and the drawing pane is the prompt 
pane. This is used whenever keyboard typein is required. 
Occasionally, messages and instructions to you (such as how to use 
the mouse for curve and line drawing) appear there too. 

Menus To the right of the drawing pane is a set of menus and 

miscellaneous panes. 

Draw Mode Menu 

The topmost menu is called the draw mode menu; it tells the 
default interpretation of mouse clicks on the drawing pane. One 
element of the draw mode menu is always highlighted, and 
specifies the current interpretation of the mouse on the drawing 
pane. Selecting (by mouse click) any item on the draw mode pane 
makes the selected mode be the new default, and highlights that 
mode. Other ways of changing the draw mode also update the 
highlighting in this pane. See the section "Drawing in FED", 
page 235. 

Under the draw mode menu appear three command menus that 
display a repertoire of commands that you can issue at any time 
by clicking on their items with the mouse. Many of the items 
interpret the different mouse buttons differently. See the section 
"FED Command List", page 259. The mouse documentation line 
at the bottom of the screen displays the interpretation of the 
mouse buttons when the mouse is positioned over a potential 
choice. 

The three command menus are grouped by related function: 

Drawing Pane Menu 

The topmost command menu (drawing pane menu) presents a 
group of commands allowing you to control how you are looking at 
what you see, and commands to perform automatic transformation 
and drawing on the character being edited. 



Gray Plane Menu 



The second command menu contains commands apropos the gray 
plane, which is, in effect, a second pane behind the drawing pane, 
whose display is shown in gray instead of black. You can use the 
gray plane to see two characters at once, to see one character as a 
model while editing another, and so on. The gray plane can be 
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moved around and manipulated in several ways. See the section 
"The FED Gray Plane", page 239. 

Outside FED Command Menu 

The third command menu contains commands dealing with the 
world outside FED: reading and writing files, getting help, leaving 
FED, and selecting and saving characters and fonts. 

Status Pane Under the command menus is the status pane, which tells you 

what font and what character is being edited. The character is 
displayed in the default Lisp Machine font: this is to be 
considered an identification of the character you are editing. For 
example, if you display the font greek9 with [Show Font], you 
see that the omega character in greek9 occupies the position that 
corresponds to W in the default Lisp Machine font. So the status 
pane identifies that character as W, but the "real" character 
(omega) is displayed in the sample pane. The status pane also 
shows you the width of the character being edited. The width is 
changed by manipulating the vertical edges of the character box; 
this action updates the status pane's display. 

Character Select Menu 

Under the status pane is the Character Select menu, which is 
used to select a character to edit. Simply clicking on an item in 
this menu (once a font has been selected) draws that character in 
magnification in the drawing pane, so you can begin editing it. 
You can also use the Character Select menu to answer any 
prompt for a character, such as those issued by the Rename 
Character and Gray Character commands. When a prompt is 
issued that can be answered by clicking on this menu, it says so 
in its text. 

Font Parameters Menu 

Under the Character Select menu is the Font Parameters menu. 
It displays the font-wide parameters, such as blinker height and 
width, and baseline and character height. This is a Choose 
Variable Values menu; by clicking on any of the numbers in it, 
the menu "opens up" and allows you to type in a new value. 
When you change a font parameter in this way, the change takes 
effect immediately. The FED frame can even change shape to 
accommodate the new parameters. All values in this menu are 
displayed and accepted in decimal, regardless of the setting of 
base and ibase. 

Register Pane The final pane of the Fed frame is the register pane, which is 

labelled Registers. It is divided into as many little boxes (registers) 
as fit; the size of the boxes is computed from the parameters of 
the current font. Registers can be used to store characters and 
pieces of characters being edited, and retrieve them, without 
storing them into any font. See the section "FED Registers". 



230 

Text Editing and Processing March 1985 



FED has an alternative configuration, or pane layout, that gives a wide aspect ratio 
(screen-wide) to the drawing pane, as opposed to the normal tall aspect ratio. The 
[Configure] menu item in the top command menu can be used to switch 
configurations. When selected, it pops up a menu of the two possible configurations. 

Many FED commands produce typeout y text and/or drawings that are "written over" 
the whole FED frame display. [Show Font] and [List Fonts] are typical of such 
commands. When a command produces typeout, the typeout remains until the next 
command is typed. Pressing space is a command that does nothing; use it to erase 
typeout and do nothing more. 



15.2 Selecting a Font 

FED edits one font at a time, and one character in that font at a time. You can 
make new fonts, and add new characters to fonts. Using FED consists of selecting a 
font, then selecting, successively, several characters in that font, editing each one in 
turn, and "storing" it back into the font. When this editing is finished, the font in 
the Lisp environment reflects all of these changes. At that time, you usually want 
to write the font out to a BFD file, to save your work. See the section "Reading 
and Writing FED Files", page 257. 

FED provides several ways to select a font. 

• You can name the font to be edited in the command or Lisp form that invoked 
FED. See the section "Entering and Leaving FED", page 225. 

• You can select the [Edit Font] menu item, which prompts for the font name in 
the prompt pane. Use [Edit Font (M)] to copy an existing font as the first step of 
making a new font. 

• You can list all loaded fonts with the [List Fonts] menu item. The display 
produced by [List Fonts] is mouse sensitive: moving the mouse over the name of 
any font highlights it, and clicking on it begins editing of that font. Using [List 
Fonts (R)] lists all fonts on the file computer as well as loaded ones. This usually 
takes a long time to produce. The keyboard command F can also be used to 
prompt for the name of a font to edit. 

15.2.1 Creating a New Font 

If you attempt to edit a font that is not known to the system, FED asks you 
whether you wish to create that font. This is the way you create new fonts. When 
you create a new font, the first thing you usually want to do is alter the font 
parameters (in the font parameters menu) and define the Space character, from 
which many facilities in the system (including some in FED) determine the "usual 
width" of characters in this font. As a matter of fact, you might want to 
reconfigure the FED frame after setting the width of Space, to correctly recalculate 
the width of registers in the register pane. 
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15.2.2 Displaying Characters in the Font 

When you start editing a font, you are not editing any character. The drawing 
pane displays a typical character box, and no points. The specifications for the 
character box reflect the Space character in the font. You must then select a 
character to edit. FED then displays all of the characters in the font, using the 
display normally obtainable by [Show Font]. You can erase this display by pressing 
space or by selecting a character to edit. See the section "Selecting a Character in 
FED", page 233. 



15.3 Selecting a Character 

Once a font has been selected, FED edits one character at a time. You modify the 
definition of the character by drawing and clearing points on the drawing plane. 
When you are done editing a character, you store it back in the font by using the 
[Save Char] menu item. Your changes to the character are not saved until you do 
this. Furthermore, none of your changes to a font being edited become permanent 
until you write the font out to a file. 

15.3.1 From the Character Select Menu 

The usual way to select the character being edited is by using the mouse to select a 
character in the Character Select menu. When you select a character, it is drawn in 
magnification in the drawing pane, and the status pane is updated to tell you what 
character you are editing. 

15.3.2 By Creating a New Character 

If you attempt to edit a character that is not in the font being edited, FED creates 
a new character. This is the way new characters are created. The new character is 
not actually saved in the font until the [Save Char] command is issued. 

15.3.3 From the [Show Font] Display 

You can also select a character by displaying all of the characters of the font being 
edited, via the [Show Font] menu item. The display produced by this command is 
mouse sensitive: when you move the mouse over the image of a character, it is 
highlighted, and if you click on it, editing of that character begins. This display is 
produced automatically when you select a font to be edited. 

15.3.4 With the c Command 

The keyboard c command can also be used to select a character. Pressing c prompts 
for a character, which can be supplied from the keyboard or the Character Select 
menu. 
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15.3.5 By Renaming Characters 

Another way to edit a character is to rename the character being edited to some 
other character. This is one way to move characters around in a font, and make 
characters into other characters. Selecting the [Rename Char] menu item prompts 
for a character to call the character being edited. You can answer this prompt 
either by typing a character from the keyboard, or from the Character Select menu. 
This changes FED's idea of what character you are editing, and the status pane and 
sample string (if any) are updated to reflect this fact. Renaming a character does 
not store it back in the font; you must do that by yourself, as usual, with the [Save 
Char] command when you are done editing it. 
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16. Drawing 



The most common technique for creating and editing characters is to draw and clear 
points on the drawing pane using the mouse. 

A nonmouse cursor can be moved around with the keyboard. Sometimes, as when 
square-counting is necessary, this is useful. See the section "The FED Nonmouse 
Cursor", page 236. 



16.1 Drawing Characters with the Mouse 

Drawing on the drawing pane is in one of three modes at any time, [Set Points], 
[Clear Points], or [Flip Points]. The highlighted item in the draw mode menu tells 
which is in effect. When you click left on a box in the drawing pane, that box is 
made black (set), or white (clear), or complemented (flip), according to the current 
draw mode. If you hold the left button down (that is, you do not release it after 
clicking left on a box) and move it around, you set (or clear or complement) all 
squares over which you pass. In this way, you can draw curves or pictures, fill in 
areas, clear old mistakes, and so forth. This is the most common operation in FED, 
and is called drawing with the mouse. 

You can change the drawing mode either by selecting another draw mode by clicking 
on an item in the draw mode menu, or by clicking middle on the drawing pane. 
Clicking middle rotates through the possible draw modes. 

When you draw with the mouse, the sample pane is not updated until you release 
the left button. (You might want to do this every now and then while drawing with 
the mouse, just to observe what you have in life-size, and then press the left button 
again, to continue drawing.) 

Often, you might want to "temporarily" change the draw mode, either because the 
draw mode menu is too distant, or the mouse is not in top shape, or because you 
really want to change the draw mode for just one or two squares. You can do this 
while drawing by manipulating the control and METfi keys on the keyboard. If you 
hold down control alone while drawing, the temporary draw mode becomes [Clear 
Points] for as long as it is held down. Similarly, METfl alone sets up [Set Points] 
mode for as long as it is held down, control and METfl together temporarily put the 
mouse in pass-over mode, in which it makes no change to any squares it passes over. 

Flip mode is useful for final touch-ups, a click at a time, rather than drawing with 
the mouse button down. Since it changes any square you click on, it is most useful 
when you fix up single squares in the final stages of editing a character. 
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16.2 The Nonmouse Cursor 

The nonmouse cursor is an "alternative mouse" that can be used to draw in the 
drawing pane. It can be useful when the mouse is not in top shape, or when you 
are doing some design that involves counting squares carefully. 

This cursor is normally not visible. It starts out in the upper left-hand corner of the 
drawing pane. You move it via the •, \, [, and ] keys, which tell the direction in 
which to move it. See the section "FED Menu and Keyboard Commands", page 259. 
When you start moving it, it appears as a smaller, blinking box inside the grid box 
over which it sits. When you draw with the real mouse, it goes away. 

The keyboard command ". " complements the box over which the nonmouse cursor 
sits. 

You can also move the nonmouse cursor in numerically specified movements using 
specialized commands. See the section "FED Command List", page 259. 
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17. Viewing and Altering a Character in the Character 
Box 



The character box is the mechanism by which you can view and alter the 
boundaries of a character being edited. The following is a description of its edges, 
and instructions for changing them. 



17.1 What the Lines Mean 

FED displays a character box in the drawing pane, to indicate the "boundaries" of 
the character being edited. These boundaries are not absolute limits outside which 
the character cannot extend; rather, they are the positions that are to be considered 
the start and end of this character when it is drawn in use. Characters in italic 
fonts and foreign scripts often extend into the "territory" of the previous or next 
character. Such "incursion" is accomplished by a character's containing points 
outside its limits. 

Left and right edges 

The left edge of the character box represents the cursor position 
at the time the character is drawn in real use. Any points to the 
left of this are in the "territory" of the previous character. The 
right edge represents the start of the next character. The 
distance between the left edge and the right edge is called the 
character width, and specifies the distance by which the window 
system increments its horizontal cursor position after drawing this 
character. Points to the right of the right edge of the character 
box are an incursion into the territory of the next character to 
the right. 

Bottom edge The bottom edge of the character box {not the line under it) 

represents the baseline of the font. The baselines of all 
characters drawn on a line, in any font, form a continuous line, 
the normal "bottom" of most characters. Points below the 
baseline are "descenders". 

Top edge The top edge of the character box represents the top of the 

character. You cannot put points above the top, but FED lets you 
draw such points, for you might move them and/or the character 
box before you save the character. FED warns and asks you 
what to do if you attempt to save a character that has points 
above its top edge; this is an error. The distance between the top 
edge and the baseline is fixed for any given font (although you 
can use FED to change the value of that number). If you are 
making a new font, you should carefully consider this parameter 
(the font's baseline) before generating any characters. 
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Character height The line below the bottom of the box represents the character 
height of the font, which is the distance between the top edge 
and this line. This distance, too, is a fixed parameter for any 
font, although you can use FED to alter it for the whole font. 
You cannot put points below this line; if you do, they appear in 
the territory of the next line when drawn, and are cleared or 
overwritten inconsistently. The maximum of the character 
heights of all fonts in the font map of a window is used to 
compute the line spacing of a window. 



17.2 Altering the Character Box 

You can move the edges of the character box on the drawing pane by clicking on 
them (within one-half box on either side) with the right mouse button. Hold the 
button down and move the line to where you want it to be, and then release the 
button. 

Moving the character box redefines the orientation of the character, as drawn, with 
respect to the other characters in the same font. 

If you attempt to move the bottom edge, top edge, or character height line, you 
move them all, and thus move the whole character box vertically. You cannot move 
them individually because the distances between them are fixed parameters for the 
font. If you alter these parameters by selecting them in the Font Parameters 
menu, the character box is altered and redrawn appropriately. 

Sometimes, you want to move the whole character box without changing its shape. 
The easiest way to do this is to move the data being displayed with the [Move 
Black] menu item. See the section "Transformations". 
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18. The Gray Plane 



The gray plane is a "shadow" "behind" the drawing pane that allows you to look at 
another character in addition to the one you are editing. The character (or piece of 
a character) in the gray plane shows up in light gray in the drawing pane. Where 
bits are on in both the gray plane and the character being edited (the black plane), 
a dark gray square is shown. 

Frequently, the gray plane is used to hold a character that resembles, or has pieces 
of, the character being edited, to serve as a guide for drawing the new character. 
At other times, the gray plane is used to hold a piece of a character, to be merged 
later into the black plane. 

The second of the three command menus is a special menu for commands dealing 
with the gray plane. It is also possible to fetch previously created patterns into the 
gray plane from the register pane. See the section "FED Registers". 



18.1 Getting Things Into Gray 

The most common ways of putting drawings into the gray plane are to move the 
black plane into it and to fetch characters into it. The [Swap Gray] and 
[Gray Char] menu items do this. 

18.1.1 With [Swap Gray] 

[Swap Gray] exchanges the black and gray planes; what had been black becomes 
gray, and what had been gray becomes black. After you use [Swap Gray], you are 
editing in the black plane what had been in the gray plane, and what you had been 
editing in the black plane (where all editing is done) is now visible in the gray plane. 
You can clear the black plane with [Erase All]; [Clear Gray] (in the gray plane 
menu) clears the gray plane. 

You can swap the gray and black plane to bring the gray plane up for editing, to 
move something you have edited into the gray plane, or to do both at once. 

18.1.2 With [Gray Char] 

You can bring characters directly into the gray plane. Using [Gray Char] prompts 
you for a character in the current font to be brought into the gray plane. You can 
then type the character, or select it in the Character Select menu. The keyboard 
command G does this, too. The character is placed at the character box. It does not 
really matter where the character is placed, though, because before merging it or 
using it, you can move it to any place in the gray plane by using [Move Gray]. See 
the section "Merging Characters with the FED Gray Plane", page 240. 
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You can bring characters from other fonts into the gray plane by using 
[Gray Char (R)]. A Choose Variable Values menu is presented, offering choices not 
only of character and font, but of scaling as well. Click on values you wish to 
change; keep in mind that the [Character] item expects a single character when you 
use it. Scaling allows you to grow or shrink the character being fetched before 
bringing it into the gray plane. The numerator and denominator of the scale 
fraction are displayed and interpreted as decimal numbers. When you are done 
choosing values for [Gray Char], use [Do It] to bring in the character. 



18.2 Merging Characters with the Gray Plane 

The gray plane is the mechanism for adding pieces of characters into characters 
being built. You do this in two steps: 

1. Put a character or a piece of a character into the gray plane and position it. You 
use the [Move Gray] command to reposition a drawing in the gray plane. It 
leaves the black plane and the character box unaffected; it moves bits within the 
gray plane only. When you use it, you are asked in the prompt pane for two 
points, which you indicate by clicking left on them in the drawing pane. These 
points indicate where from and where to move the data in the gray plane. FED 
temporarily grays (in a distinguishable gray) the points you select so that you can 
see them, and then moves all the data in the gray plane so that the first point is 
moved to the second. Usually, rather than clicking random points, you should 
click a specific point in the gray drawing and the point in the black drawing with 
which you wish the gray point to coincide. You might also think of these points 
as a point in the gray plane and a point in the black plane to which the point in 
the gray plane is to be made to coincide. 

2. Merge it into the black plane. The [Add in Gray] command merges the gray 
plane into the black plane. Normally, you use [Add in Gray]. This turns on 
(makes black) each point in the black plane that is "over" a turned-on (gray) point 
in the gray plane, and leaves the gray plane as it was. Thus, the points that 
were gray now all appear in dark gray, indicating they are on in both planes. 
Using [Add in Gray (M)] is similar, but clears the gray plane afterwards. 

You can also merge the gray plane into the black plane by other logical operations 
than the default Inclusive Or: using [Add in Gray (R)] pops up a menu of logical 
combination operators. ANDCA (turn off all black points corresponding to "on" 
points in the black plane, that is, punch a hole in the black plane as indicated by 
the gray plane) and XOR (flip all points in the black plane that are on in the gray 
plane) are offered, as well as the default value, IOR. 
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19. Saving Characters and Pieces of Characters in 
Registers 



FED's gray plane allows you to edit one character or piece of a character. You can 
also save characters and pieces in registers. The register pane shows the contents of 
registers that can hold characters and pieces of characters for reuse. 



19.1 Saving a Drawing Into a Register 

You save a drawing (in the black plane, after editing) by clicking left on one of the 
empty registers (little boxes) in the register pane. Do not use the first (upper left- 
hand) one. Clicking left on an empty register (one that looks blank) saves the 
current black drawing in that register. Registers are mouse-sensitive, and grow a 
thick border when you move the mouse over them. Click on an empty register, and 
the drawing in the black plane appears in that register, in the register pane, and 
remains there. FED makes every effort to show you a visible piece of that 
character, so that you know it is there. 



19.2 Retrieving the Contents of a Register 

To retrieve a register, click left on it, and the contents of the register are 
transferred into the black plane. If you click on a register that has a drawing in it, 
that drawing goes into the black plane. If it does not have a drawing in it, the 
black plane goes into it. Thus, clicking left on registers is usually the only dealing 
you have with them. 



19.3 Retrieving the Black Plane While Manipulating Registers 

You might click on a different register than the one you intended. Or perhaps a 
register is not really empty, but has a peculiar drawing in it that has a gigantic 
empty middle. In either of these cases, you might lose the very work in the black 
plane that you were trying to save. Thus, FED always copies the current black 
plane into the upper left-hand register when fetching the contents of a register, in 
case you made a mistake. You can then click on the upper left-hand register to 
retrieve its contents. 

Drawings saved in registers are saved as bits; the orientation and size of the 
character box are not saved. 

It is possible to save the gray plane into a register, or fetch a register into the gray 
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plane. It is also possible to store into a nonempty register from either plane. If you 
want to do any of these operations^ click right on a register, and a menu of possible 
operations pops up. 
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20. Transformations 



Although drawing with the mouse is the most common way to create characters and 
pieces of characters, FED can provide a good deal of automatic drawing help, such as 
drawing lines and curves and performing transformations on the character being 
edited. As is true of drawing with the mouse, all of these operations are applicable 
only to the black plane. If you want to perform them on the gray plane, swap 
planes, perform them, and swap back. 



20.1 Clearing the Drawing 

The simplest operation on a drawing is getting rid of it; [Erase All] clears the entire 
(black) drawing. The gray drawing, if any, is left intact. You are queried to make 
sure you really want to clear the entire drawing. This function is also accessible via 
the keyboard command E. 



20.2 Rotating Drawings 

FED can rotate characters 90 degrees right or left, or 180 degrees. Rotations are 
performed about the center of the square whose top, right, and left edges are the 
top, right and left edges of the character box, and thus, whose bottom must be, and 
is, a distance below the top of the character box equal to the character width. 

Rotation Mouse command 

90 degrees right [Rotate (R)] 

90 degrees left [Rotate] 

180 degrees [Rotate (M)] 

Note that rotating the drawing 180 degrees is not the same as turning it upside 
down. 



20.3 Reflecting Drawings 

FED can reflect drawings about any of four lines. Using [Reflect] pops up a menu 
of the four lines about which to rotate the drawing. Those lines all pass through 
the "center" of the character box, the point halfway between the left and right 
edges and halfway between the top and the bottom line, not the baseline. 

These lines are the horizontal and vertical lines through the center point, the 

X Axis ( | ) and the Y Axis (-), and the 45-degree diagonals, the line X=Y (/), and the 

line X= -Y (\), through it. 
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Reflection is subtle; it is very different than rotation. Imagine the drawing as made 
of sheet metal, lying on the plane. Rotation moves the character around in the 
plane, turning it, but never lifting it off the plane. Reflection picks it up, and puts 
it back, face down on the plane. The effects of diagonal reflections are subtle. The 
best way to understand these commands is to edit an asymmetrical but simple 
character (the one of choice is F) in a straightforward font (for example, HL12B), 
and try these various reflections upon it, as well as the rotations. 



20.4 Moving the Drawing 

You can move the drawing around with [Move Black]. [Move Black] moves the 
drawing with respect to the character box, the drawing pane itself, and the gray 
plane. [Move Black] prompts for two points, a point in the black plane and a point 
to which to move it. The whole black drawing moves along with it as well. 



20.5 Drawing Lines and Curves 

FED can draw approximate lines and curves in the drawing. Rather than drawing 
actual lines and curves on the drawing, FED manipulates squares along the line or 
curve desired. Thus, if you ask to draw a line that is not straight up, down, or 
across, FED approximates as well as it can. 

To draw a line, use [Draw Line], and select two points between which to draw a 
line. As with all commands in which FED prompts for points, the points are 
temporarily grayed when you click on them, to verify your choices. The line is 
drawn in the current draw mode, which means it clears a line if appropriate, or even 
flips all the points along one (which is hardly ever appropriate). 

To draw a curve, use [Draw Spline]. Then click left on all the points through which 
the curve is to pass. When you are done, use [Draw Spline (R)]. The spline- 
drawing package is called to compute the points of an unconstrained cubic spline 
through these points, and the approximate curve is drawn in the current draw 
mode. See the section "Drawing Splines on Windows" in Programming the User 
Interface. 



20.6 Stretching and Contracting 

FED can stretch or contract drawings. This is not the same as growing or 
shrinking them. Stretching means inserting duplicate rows or columns at a given 
point of the drawing, and contracting means removing rows or columns. Growing 
and shrinking, in general, mean scaling the whole drawing up or down. The latter 
is done with the options to [Gray Char]. See the section "Getting Things Into the 
FED Gray Plane", page 239. 
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The relative orientation of the first and second points clicked on specifies whether 
you want to stretch or to contract. 

20.6.1 Stretching a Drawing Horizontally 

Stretching a drawing horizontally means making some number of copies of a column 
of squares to the right of that column. To stretch a character horizontally, use 
[Stretch], and then click left on any square in the column to be "stretched". Then 
click left on any square in the column to the right of that to which that column is 
to be stretched (that is, the last column to be a duplicate of the column being 
stretched). The entire drawing is stretched, with the required number of copies of 
the duplicated column inserted. 

20.6.2 Contracting a Drawing Horizontally 

Contracting a drawing horizontally means eliminating some number of columns of 
squares. To shrink a character horizontally, use [Stretch]. Then click left on any 
square in the rightmost column not to be eliminated, at the right edge of the 
columns to go, and then on the leftmost column to be eliminated. You should think 
of this as clicking on a column to move, and where to move it to. 

20.6.3 Stretching a Drawing Vertically 

Stretching a drawing vertically means making some number of copies of a row of 
squares below that row. To stretch a character vertically, use [Stretch (M)], and 
then click left on any square in the row to be "stretched". Then click left on any 
square in the row below that to which that row is to be stretched (that is, the last 
row to be a duplicate of the row being stretched). The entire drawing is stretched, 
with the required number of copies of the duplicated row inserted. 

20.6.4 Contracting a Drawing Vertically 

Contracting a drawing vertically means eliminating some number of rows of squares. 
To shrink a character vertically, use [Stretch (M)]. Then click left on any square in 
the topmost row not to be eliminated, at the top edge of the rows to go, and then 
on the topmost row to be eliminated. You should think of this as clicking on a row 
to move, and where to move it to. 
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21. The Sample String 



When you edit a font, it is usually convenient to maintain a sample string, displayed 
in the font, so that you can see how the character you are editing looks in the 
context of other characters next to which it might appear. 

FED allows you to set a sample string. The straightforward method of setting it is 
to select the [Set Sample] menu item: doing so prompts you for the string, which 
should be short enough to fit in the sample pane (it is clear if it does not, as you 
only see the end of it). End the string by pressing return. The string is then 
displayed in the sample pane. 

If the sample string contains the character being edited, occurrences of that 
character are updated whenever any change is made to the drawing. Thus, the 
occurrences of the character being edited in the sample string reflect the state of the 
current drawing, not the state of that character stored in the font. 

Two other ways to ask FED to prompt you for the sample string are clicking any 
button on the sample pane itself, and issuing the v command from the keyboard. 
This last is often the most convenient, because you are then going to type the string 
itself. 
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22. Adjusting the Display 



The commands and facilities described here deal with positioning the drawing display 
and modifying its visible characteristics. They do not actually change the data in 
the drawing, but rather, the way it is viewed. 



22.1 Positioning the Drawing 



Both the black and gray drawings can be thought of as being drawn on an infinite 
plane. The character box is in the center of that plane. Although [Move Black] and 
[Move Gray] exist to move the drawings, and the character box can be moved by 
clicking on it, sometimes you might want to reposition the entire drawing, character 
box, black drawing, gray drawing, and all. This can also be viewed as repositioning 
the view of the drawing offered by the drawing pane. FED provides several 
techniques for repositioning the entire drawing. 



[Move View] 



[Center View] 



Scrolling 



The simplest is [Move View]. [Move View] works just like 
[Move Gray] and [Move Black]. When you use [Move View], it 
prompts you for two points, which you indicate by clicking left on 
squares on the drawing pane. The first point is a point on the 
drawing; the second is a point in the pane to which to move it. 
The whole drawing is moved, perhaps simultaneously vertically 
and horizontally, so that the first point is where the second point 
had been. 

Another common need is to recenter the drawing, that is, put the 
character box back in the middle. This is the way the drawing 
pane starts out when you begin editing a character. The [Center 
View] menu item performs this task. Use [Center View] to 
recenter the drawing. The keyboard H (for Home) command does 
this too. 

Another way to reposition the display is to scroll it up or down or 
left or right. In order to scroll the display vertically, a scroll bar is 
provided at the left of the drawing pane. When you move the 
cursor to the extreme left edge of the drawing pane and bounce 
the cursor at that edge, the cursor changes to a double-pointed 
arrow and the left margin of the drawing pane displays a graph of 
the vertical portion of the drawing you are looking at. The status 
line documentation reflects the possible options at this point. 

To scroll the drawing horizontally, a scroll bar is provided at the 
bottom of the drawing pane. When you move the cursor to the 
extreme bottom edge of the drawing pane and bounce the cursor 
at that edge, the cursor changes to a double-pointed arrow and 
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the bottom edge of the drawing pane displays a full-grid length 
graph of what horizontal portion of the drawing you are looking 
at. The status line documentation reflects the possible options at 
this point. 



22.2 Setting the Box Size in the Drawing Pane 

You can set the size of boxes in the drawing pane. Normally, it is 12, meaning each 
box, corresponding to one pixel of the actual character, is represented by a box 12 
pixels wide and high. To set the size of boxes, use [Grid Size]. FED prompts you 
for the size of a box, in decimal. This size can not be bigger than 64 pixels. If you 
type a carriage return without typing any number, the default size of 12 pixels is 
reestablished. 



22.3 Setting the Height and Width of the Drawing Pane 

You can tell the FED frame to show either a wide drawing pane, as wide as the 
screen, or a tall drawing pane, almost as tall as the screen. These two 
configurations of the frame are chosen from a pop-up menu that is obtained by 
using [Configure]. This command can also be used to have FED recompute its 
configuration, for example, to reshape its registers after you have edited the Space 
character of a font. 
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23. Reading and Writing Files 



FED can read and write files containing fonts in any of a variety of formats. The 
most common format is BFD, the standard font format of the Symbolics Lisp 
Machine. If you are making fonts for use by the Symbolics Lisp Machine display 
and window system or the LGP-1, this is the only format you should ever have to 
deal with. 

Most of the other formats are for compatibility with other systems and earlier 
releases of the Symbolics Lisp Machine software. Notable among these formats is 
PXL format, which is a standard font format with the TEX system on UNIX. BFD 
format is the default for all file reading and writing operations. 



23.1 Reading Files 

Use [Read File] and type in the file name to read in a font file. The file type 
defaults from the (canonical) type of the pathname presented as the default. For 
example, if you type fix9.bfd, or just fix9, you read a BFD file, whereas if you type 
fix9.bin, you read a BIN file. FED complains if you supply a file type that is not a 
valid font file type for the machine you are using. Pressing R is equivalent to using 
[Read File]. 

From outside of FED you can use Dired to read in any font file. Enter Dired, move 
point to the line showing the font file, and press fl (which queues a file to be acted 
on by a function). Apply the fed function to that file to read it in. 

When you read in a font via [Read File], it is actually loaded. It becomes part of the 
Lisp environment, and appears in listings of loaded fonts produced by [List Fonts] as 
well as by the Show Font command and by Zmacs. After FED loads the file and 
looks for the font you specified, you are editing that font. 

It is sometimes necessary to read in font files of exotic types, whose file types (as 
expressed in the name of the file) are not indicative of the format of the font. For 
instance, you might have renamed a BFD or other file to my font, temp, and now you 
want to read it in. Since FED cannot determine the font format from this file type, 
you must specify the font format explicitly. This is done by using [Read File (R)]: 
FED offers a menu specifying file types. Click on the fije type involved: FED then 
prompts for a pathname and reads the file. FED interprets the file, however, 
according to the format specified by the menu, not by the, file type. 
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23.2 Writing Files 

FED can also write out font files. Files are written from the description of a font 
residing in the Lisp environment, not from any temporary FED image of the font. 
Since FED maintains no temporary image of the font, but actually stores edited 
characters back in the font when you use [Save Char], this is not a problem unless 
you forget to save your characters. 

Use [Write File] to write the font file out. The file type defaults from the 
(canonical) type of the pathname presented as the default. For example, if you type 
newfnt.bfd, you write a BFD file, whereas if you type newfnt.bin, you write a BIN 
file. FED complains if you supply a file type that is not a valid font file type for the 
machine you are using. Using [Write File] writes out a BFD file by default from a 
font description in the Symbolics Lisp Machine virtual memory. The default 
directory is the system screen fonts directory; the default file name is font.bfd, where 
font is the current font being edited. Pressing W is equivalent to using [Write File]. 

It is sometimes necessary to write out font files of exotic types, whose file types (as 
expressed in the name of the file) are not indicative of the format of the font. For 
instance, you might already have a sfnt.bfd, and want to write your file to 
sfnt.temp. Since FED cannot determine the font format from this file type, you 
must specify the font format explicitly. This is done by using [Write File (R)]: FED 
offers a menu specifying file types. Click on the file type involved: FED then 
prompts for a pathname and writes the file. FED writes the file, however, according 
to the format specified by the menu, not by the file type. 
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24. Command List 



The following is a listing of all FED commands. The first part of this listing 
describes the commands available via the command menus and the keyboard. When 
a keyboard character exists duplicating a menu command, it is given in addition after 
the command name. The second part of this section describes the effect of clicking 
on various panes and mouse-sensitive areas of the FED frame. 

Many of the keyboard commands take numeric arguments to specify some number or 
character. Numeric arguments are entered by typing a decimal number before the 
command character. The numeric argument is echoed in the prompt window as you 
enter it. 



24.1 Menu and Keyboard Commands 



24.1.1 Configuration and Drawing Transformation 



[Configure] 
[Grid Size] 

[Center View] H 
[Move View] 

[Draw Line] 

[Draw Spline] 

[Erase All] E 
[Stretch] K 



Pop up a menu of frame configurations. Two configurations are 
offered, giving a tall and wide aspect ratio to the drawing pane. 

Set the size of boxes in the draw pane. If a numeric argument is 
given, it is used as the size. @ sets grid size to the default if 
given no numeric argument, but [Grid Size] prompts. 

Reposition the display in the drawing pane so that the character 
box is centered in it. 

Reposition the display in the drawing pane by prompting for two 
mouse-specified points: which point to move and to which point to 
move it. 

Draw a line in squares in the drawing pane, in the current 
drawing mode. Prompt for two endpoints, to be specified with the 
mouse. 

Draw a cubic spline in squares in the drawing pane, in the 
current drawing mode. Prompt for curve points, to be specified by 
using [Draw Spline]. Using [Draw Spline (R)] ends the curve. 

Clear all points (black points) in the current drawing. 

Stretch or contract a character, horizontally or vertically. 
[Stretch] is horizontally, [Stretch (R)] is vertically. FED prompts 
for two points, specifying a row or column to move and to where 
to move it. From the keyboard, K means horizontal, c-K means 
vertical. See the section "Stretching and Contracting Drawings in 
FED", page 246. 
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[Rotate] e Rotate the drawing in the black plane. [Rotate] is 90 degrees to 

the left, [Rotate (R)] 90 degrees to the right, and [Rotate (M)] 180 
degrees. 

[Reflect] £ Reflect the drawing in the black plane about a coordinate axis or 

diagonal line through the center of the character box. A menu 
pops up, asking which. 

[Move Black] Move the drawing in the black plane. You are prompted for the 

target and destination points, which you specify by clicking left on 
the drawing pane. 

24.1.2 Gray Plane Menu Items 

[Gray Char] G, also M 

Place a character into the gray plane. The keyboard commands 
accept numeric arguments to specify which character. If none is 
given, or if you use [Gray Char], you are prompted for a 
character, which you can supply from the keyboard or the 
Character Select menu. If you use [Gray Char (R)], you are 
offered a Choose Variable Values choice window to select the 
character, font, and scaling. For the keyboard commands, CONTROL 
causes FED to prompt for a font name, and METfl causes it to 
prompt for scale factors. 

[Clear Gray] Clear the entire gray plane. 

[Swap Gray] Exchange the drawings in the gray and black planes. 

[Move Gray] Move the drawing in the gray plane. You are prompted for two 

points, to be specified via the mouse, a point to move and a point 
to which to move it. 

[Add in Gray] Combine the drawing in the gray plane into the black plane. 

Using [Add in Gray] inclusive-or's the gray drawing into the black 
drawing. Using [Add in Gray (M)] inclusive-or's the gray drawing 
into the black drawing, and clears the gray drawing. [Add in 
Gray (R)] pops up a menu of other combination modes. 

24.1.3 Outside World Interface Menu Items 

[Edit Font] F Pick a font to edit. You are prompted for the font name. Use 
[Edit Font (M)] to copy an existing font as the first step of 
making a new font. 

[List Fonts] [List Fonts] lists all of the loaded fonts. [List Fonts (R)] lists all 

of the loaded fonts and fonts on the file computer. The display is 
mouse-sensitive; clicking left on any item begins editing that font. 

[Save Char] S Store the character being edited back into the font in the Lisp 
environment. It is stored as the character that the status pane 
indicates it to be. 
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[Rename Char] c-c 

Rename the current character; make it seem as though you are 
now editing a different character, but retain the drawing. You 
are prompted for the character, which you can supply from either 
the keyboard or the Character Select menu. The keyboard 
command accepts a numeric argument to specify the character. 



[Show Font] D 



[Set Sample] V 



[Read File] R 



[Write File] U 



Display all characters in the font being edited. The display is 
mouse-sensitive, and clicking left on a character begins editing 
that character. 

Prompt for the sample string to be displayed in the font being 
edited in the sample pane, and set it. 

Read in a file of font definitions. Prompts for a pathname. [Read 
File] computes the font file type from the file type of the 
pathname given. The default is always BFD. [Read File (R)] 
pops up a menu that offers the file types: BFD, KST, BIN, AC, 
AL, PXL, or Any. The file specified by the pathname given will 
be interpreted according to that format, regardless of file type. 

Writes a file of font definitions. Prompts for a pathname. [Write 
File] computes the font file type from the file type of the 
pathname given. The default is always BFD. [Write File (R)] 
pops up a menu that offers the file types: BFD, KST, BIN, AC, 
AL, PXL, or Any. The file specified by the pathname given will 
be written in that format, regardless of file type. 



Bury the Font Editor, and return to whatever you were doing 
when you last invoked FED. 



[EXIT] Q 

[HELP] HELP or ? Display a long message giving documentation of FED 



24.1.4 Evaluating Forms From FED 

FED uses the ESCAPE key to evaluate a Lisp form. 

24.2 Keyboard-only Commands 



The following commands are accessible only from the keyboard. They are mainly 
concerned with the nonmouse cursor, or general interaction with the subsystem. 

\ Turn the nonmouse cursor on, and move it one position up the 

screen. A numeric argument tells to move it other than one 
position. c-\ and n-\ mean 2 and 4 positions, respectively, and 
c-n-\ means 8. 

/ Same as \, but moves the nonmouse cursor down. 

[ Same as \, but moves the nonmouse cursor left. 
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] Same as \, but moves the nonmouse cursor right. 

When the nonmouse cursor is on, complement the black square 
under it. 

REFRESH Redraw the drawing pane. Useful in case of perceived problems. 

c-REFRESH Clear the screen and refresh all panes in the FED frame. 

ABORT Abort any command while it is prompting* waiting for either 

mouse or keyboard input. 

C Begin editing a character: prompt for the character, and begin 

editing it. Normally, you simply select a character from the 
Character Select menu or the [Show Font] display, c accepts a 
character specification as a numeric argument. 



24.3 Mouse Sensitivities 

This section describes the result of clicking the mouse on various portions of the 
FED frame other than the command menus. 

24.3.1 The Drawing Pane 

Click left Draw a black square in the current draw mode, which is shown 

by the Draw Mode menu. It continues drawing as the mouse is 
moved as long as the left button is held down. Pressing control 
while drawing means temporarily go into [Clear Points] mode 
(METfl means [Set Points] mode); neither changes any points. 

Click middle Change the draw mode, cycling through the three possible draw 

modes. 

Click right Only meaningful when the mouse is over a boundary of the 

character box. "Pick it up" and begin moving it as the mouse is 
moved, as the right button is held down. 

The drawing pane has a scroll bar at its left edge. 

24.3.2 The Draw Mode Menu 

Clicking any button on one of the draw modes selects that draw mode until it is 
next changed by clicking on this menu, or clicking middle on the drawing pane. 

24.3.3 The Sample Pane 

Clicking any button on the sample pane prompts for a new sample string. 
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24.3.4 The Character Select Pane 

Clicking left on any character in the character select pane begins editing it. The 
character select pane can also be used to answer any command that is prompting for 
a character. 

24.3.5 The Font Parameters Menu 

Clicking left on any item in the Font Parameters menu opens it for editing. You 
are expected to type a new decimal number. As soon as you press return, the 
altered parameter is stored in the font in the Lisp environment. 

24.3.6 The Register Pane 

Click left On an empty register, store the current black plane drawing in 

that register. On a nonempty register, retrieve the drawing in it 
into the black plane, and store the current black plane drawing 
into the upper-leftmost register. 

Click right Pop up a menu allowing the register you clicked on to be loaded 

from either plane (regardless of whether or not it is empty) or 
retrieved to either plane. 

24.3.7 The List Fonts and Show Font Displays 

These displays are mouse-sensitive. Clicking left on a font in the [List Fonts] display 
begins editing it; clicking left on a character in the [Show Font] display begins 
editing that character. 
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PART III. 



Hardcopy System 
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25. Printing and Hardcopy Commands 



25.1 Commands for Producing Hardcopy 

You can produce hardcopy using the System Menu, from the editor, from Zmail, 
from Dired in the editor, and from the file system editor. You can also get a 
hardcopy of your screen at any time. 

In order for menu items, commands, and functions that refer to printing and 
hardcopy to work, your site must have a properly connected printing device. 
Printers are objects in the namespace database. See the section "Namespace System 
Printer Objects" in Networks. 

25.1.1 Hardcopying From the System Menu 

To produce hardcopy using the System Menu, click on [Hardcopy]. This pops up a 
menu that allows you to specify the pathname of the file to be hardcopied, the 
printer to send it to, and some options for format. 

25.1.2 Hardcopying From Zmacs 

You can hardcopy a region, a buffer, or a file from Zmacs. 

Hardcopy Region (n-x) 

Sends a region's contents to the local hardcopy device for printing. 

Hardcopy Buffer (n-x) 

Prompts for the name of a buffer and then prints the specified 
buffer on the local hardcopy device. 



Hardcopy File (m-x) 

Sends a file to the local hardcopy device for printing. 

Kill Or Save Buffers (m-X) 

Puts up a multiple-choice menu listing all existing buffers. Choices 
are: Save, Kill, Unmodify, and Hardcopy. Specify these options next 
to the buffer names in the menu. This command appears on the 
editor menu. 
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25.1.3 Hardcopying From Zmail 

You can hardcopy a single message or a collection of messages from Zmail. 

Action Command 

One message [Move / Hardcopy] 

Click right on its summary line 
then [Move / Hardcopy] 

All messages in current sequence [Map over / Move / Hardcopy] 

In any of these commands you can use [Hardcopy (R)] to get a menu that permits 
you to specify the number of copies, the font, and which printer to use. The other 
option in the list of printers allows you to specify an arbitrary printer, using either 
its pretty name or its namespace name. This printer becomes the selected printer, 
and remains in the menu for subsequent hardcopy commands. 

25.1.4 Hardcopying From Dired 

You can mark files to be hardcopied in Dired. When you exit from Dired, the files 
marked to be hardcopied are sent to the printer. 

P Dired Hardcopy File 

Marks the current file for printing. Dired puts a P in the first 
column to show that the file has been so marked. 

With a numeric argument n y marks the next n files for printing. 



25.1.5 Hardcopying the Screen 

You can get a hardcopy of what is displayed on your screen by pressing function Q: 

Q Hardcopies the entire screen. 

c-Q Hardcopies the selected window. 

n-Q Hardcopies the entire screen, minus the status and mouse 

documentation lines. 

25.1.6 Hardcopying From the File System Editor 

You can invoke the system hardcopy menu from FSEdit. You click on Hardcopy in 
the menu of file operations invoked by clicking right on a file name. 
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25.2 Other Hardcopy Commands 

25.2.1 Changing the Default Printer 

When a site has more than one printer, one of the printers is specified as the site 
default hardcopy device. You can change the default in your init file to specify the 
printer that is most convenient for you. See the function 
sitset-default-hardcopy-device, page 271. 

In the System Menu, using [Hardcopy] allows you to specify a different printer 
name; the printer name is mouse-sensitive. 

25.2.2 Checking the Status of Hardcopy Devices 

You can find out the status of a hardcopy device in Zmacs: 

Show Hardcopy Status (m-X) 

Show the status of a hardcopy device or all of them. 
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26. Customizing Hardcopy Facilities 



You can specify the printer you want to use for hardcopying files and screen images 
in your init file. 

si:set-default-hardc<opy-device name Function 

sirset-default-h&rdcopy-device specifies the printer to be used for all of the 
hardcopy commands except the screen copy command, name is a string 
specifying the device name. This is the real name of the printer, its name 
attribute not its pretty-name. For example: caspian-sea is the real name 
of the printer whose pretty name is Caspian Sea. (The valid set of device 
names are the printer objects in your namespace database.) 

si:set-screen-hardcopy-device name Function 

sitset-screen-hardcopy-device specifies the printer to be used for screen 
copies (by the FUNCTION Q command), name is a string specifying the device 
name. This is the real name of the printer, its name attribute not its 
pretty-name. For example: caspian-sea is the real name of the printer 
whose pretty name is Caspian Sea. (The valid set of device names are the 
printer objects in your namespace database.) 

You can specify personal default fonts for each device in your init file. 

si:*hardcopy-default-fonts* Variable 

si:*hardcopy-default-fonts* is a variable whose value is an association list 
where each element specifies a device and a set of keyword/value pairs 
designating the font. The keywords are :default-font and :header-font. 

For example: 

(login-forms 
(setq si :*hardcopy-default-fonts* 

'(("Itasca" :default-font "Fix18B M )))) 

in your init file will specify Fixl8B as the default font for the printer Itasca. 

You can use Show Font HELP in the Lisp Listener or the List Fonts (n-x) 
command in Zmacs to get a list of all the fonts that are currently loaded into 
the Lisp environment. The fonts package contains the names of all fonts. 
Here is a list of some of the useful fonts: 

fontsrcptfont This is the default font, used for almost 

everything. 

fonts:jessl4 This is the default font in menus. It is a 

variable-width rounded font, slightly larger and 
more attractive than medfnt. 
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fonts:cptfonti 

fonts:cptfontcb 

fonts:medfht 
fonts:medfhb 

fonts:hll2i 

fonts:trlOi 

fonts:hllO 
fonts:h!10b 



This is a fixed-width italic font of the same 
width and shape as fonts:cptfont, the default 
screen font. It is most useful for italicizing 
running text along with fontsrcptfont. 

This is a fixed-width bold font of the same 
width and shape as fontsrcptfont, the default 
screen font. 

This is a fixed-width font with characters 
somewhat larger than those of cptfont. 

This is a bold version of medfnt. When you 
use Split Screen, for example, the [Do It] and 
[Abort] items are in this font. 

This is a variable-width italic font. It is useful 
for italic items in menus; Zmail uses it for this 
in several menus. 

This is a very small italic font. It is the one 
used by the Inspector to say "More above " and 
"More below ". 

This is a very small font used for nonselected 
items in Choose Variable Values windows. 

This is a bold version of hllO, used for selected 
items in Choose Variable Values windows. 
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27. Hardcopy Functions 



This chapter contains a list of some of the Lisp functions that refer to hardcopy 
facilities. 

si:hardcopy-text-file file-name device &key (page-headings t) Function 

(interpret-font-changes nil) &allow-other-keys 
si:hardcopy-text-file calls si:hardcopy-from-stream to do its work. Only 
one of the keywords :fonts, :press-fonts, or :tv-fonts should be given. The 
argument to these keywords is a list describing which fonts to use. The first 
element of the list corresponds to font in the text file or font A in Zmacs. 
For example, to print a file on an LGP using the fonts TIMESROMAN10 
and TIMESROMAN10B: 

(si : hardcopy- text- file M f :>cwh>proposal .text" si :*default-hardcopy-device* 

* : interpret-font-changes t 
': fonts '("TIMESROMAN10*' "TIMESROMANIOB")) 

The argument to the :fonts keyword is a list of device-specific fonts. If the 
output device is an LGP, it must be a list of strings representing LGP fonts. 
If the output device is a window, it must be the same as the argument to 
the :tv-fonts keyword. If the output device is the Dover, it must be the 
same as the argument to the :press-fonts keyword. 

The argument to the :tv-fonts keyword is a list of symbols in the fonts 
package that represent fonts for the Lisp Machine screen. For example: 

' :tv- fonts '( fonts :tr 10 fonts :tr 10b) 

If the hardcopy device is not a window, an attempt is made to translate the 
names of the fonts for the Lisp Machine screen into the names of fonts for 
the appropriate device. 

The argument to the :press-fonts keyword is a list of triples representing 
Press fonts. For example: 

'rpress-fonts ' ( ( "TIMESROMAN" "" 10.) ( "TIMESROMAN" "B" 10.)) 

This keyword should be of interest only to those sites having a Xerox Dover 
printer. 

The change to si:hardcopy-from-stream is for interim use at sites with a 
stand-alone Lisp Machine and LGP that use Zmacs as a text formatter. This 
also allows Japanese text to be printed on the LGP. Currently, the only way 
to print text files in multiple fonts is to call this function directly. No option 
exists for multiple fonts in the hardcopy menu. 

si:hardcopy-from-stream stream device &rest options &key Function 

(page-headings t) (interpret-font-changes nil) 
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&allow-other-keys 
si:hardcopy-from-stream recognizes font shift characters in files written by 
Zmacs. To print a file using multiple fonts, call si:hardcopy-text-file with t 
as the value of the keyword :interpret-font-changes, and also include one 
of the keywords :fonts, :press-fonts, or :tv-fonts. 

sirmake-hardcopy-stream device &key fonts landscape-p Function 

Returns a hardcopy stream to the given device. This stream accepts the 
normal output stream messages, such as :tyo, :string-out, and some specific 
hardcopy messages outlined below. 

Keyword Explanation 

rfonts A list of device-dependent fonts, for example, 

T'timesromanlO" "timesromanlOb") 

rlandscape-p t Causes the page to be printed with the long side 
horizontally. 

Example, 

(with-open-stream (stream (sirmake-hardcopy-stream si :*default-hardcopy-device*)) 

(send stream ' :string-out "this is a test 
of the hardcopy system.")) 

reject-page of si:make-hardcopy-stream Method 

Starts a fresh page. This is the same as :tyo #\page. 

:set-font new-font of sirmake-hardcopy-stream Method 

Changes the current font of the stream, new-font can be either a 
number, which is an index into the stream's list of fonts, or a string, 
as given in the initial rfonts to sirmake-hardcopy-stream. An error 
is given if the new-font is not in the list of fonts. 

:set-cursorpos x y &optional (units '.-device) of Method 

sirmake-hardcopy-stream 

Moves the place where printing occurs on the page to a new position. 
Unlike the Lisp Machine display, the 0,0 point of hardcopy streams is 
in the lower-left corner, the first Cc) coordinate increasing toward the 
right of the page, the second (y) coordinate increasing toward the top 
of the page. 

units specifies the format of x and y. .-device means that the 
interpretation is device-dependent, .-micas means x and y are in 
micas. 

rshow-rectangle width height of Method 

sirmake-hardcopy-stream 

Draws a filled-in rectangle on the page with the lower-left corner at 
the current position of size width x height 
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Note: currently, width and height are always in device-dependent 

units. Use 

(: method si:make-hardcopy-stream :convert-to-device-units) to 

convert from other units. 

:convert-to-device-units quantity units direction of Method 

si:make-hardcopy-stream 

Converts quantity in units into the corresponding quantity in device 
units, direction is either :horizontal or :vertical. 

:show-line to-x to-y of si:make-hardcopy-stream Method 

Draws a line on the page from the current position to the position 
designated by to-x, to-y. 

Note: currently, the coordinates given to this message are different 
from those given to :set-cursorpos, in that the former do not add in 
the margins of the page, but the latter do. Use 
Omethod si:make-hardcopy-stream :un-relative-coordinates) to 

convert. 

:un-relative-coordinates x y &optional (units '.-device) of Method 

sitmake-hardcopy-stream 

Converts the point x,y as would be given to messages like 
:set-cursorpos that take coordinates relative to the page margins for 
use with messages like :show-line that take absolute coordinates. 

Example: 
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(defun hardcopy-test (&optional (device si :*default-hardcopy-device*)) 
(with-open-stream (stream (si :make-hardcopy-stream 

device 

•: fonts '("TIMESROMAN10" "TIMESROMAN20"))) 
(send stream ' :set-cursorpos (* 2 2540.) (* 2 2540.) Arnicas) 
(send stream ':string-out "This is a test.") 
(send stream * :set-cursorpos (* 4 2540.) (* 7 2540.) 'rmicas) 
(send stream ':set-font 1) 
(send stream 'rstring-out "Yow!") 

(send stream * :set-cursorpos (* 3 2540.) (* 4 2540.) 'rmicas) 
(send stream ' rshow-rectangle 

(send stream 'r convert-to-device-units (* 3 2540.) 'rmicas ' rhorizontal) 
(send stream * :convert-to-device-units (* 1 2540.) 'rmicas 'rvertical)) 
(let ((x-1 (* 3 2540.)) 
(y-1 (* 6 2540.)) 
(x-2 (* 6 2540.)) 
(y-2 (* 8 2540.))) 
(multiple-value-bind (abs-x-1 abs-y-1) 

(send stream 'run-relative-coordinates x-1 y-1 'rmicas) 
(multiple-value-bind (abs-x-2 abs-y-2) 

(send stream ' :un-relative-coordinates x-2 y-2 'rmicas) 
(send stream ' :set-cursorpos x-1 y-1 'rmicas) 
(send stream ':show-line abs-x-1 abs-y-2) 
(send stream ' :set-cursorpos x-1 y-2 'rmicas) 
(send stream ':show-line abs-x-2 abs-y-2) 
(send stream ' :set-cursorpos x-2 y-2 'rmicas) 
(send stream ':show-line abs-x-2 abs-y-1) 
(send stream ' :set-cursorpos x-2 y-1 'rmicas) 
(send stream 'rshow-line abs-x-1 abs-y-1)))))) 
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